Before you start writing code, you need a local development environment. This typically includes a local server (such as XAMPP, MAMP, or Local by Flywheel), PHP, a MySQL database, and a code editor (such as VS Code or Sublime Text). Make sure that your PHP version meets the official requirements of WordPress.
Next, in the WordPress installation directory under your website, locate the wp-config.php file and open it in a text editor.wp-content/themesIn the folder, create a new folder, for examplemy-first-themeThis folder will store all the files related to your theme.
A basic WordPress theme only requires two files:style.cssandindex.phpFirst of all, create…style.cssEdit the file and add a subject information annotation to the file header, which is necessary for WordPress to recognize the theme.
Recommended Reading Customized WordPress Themes: A Complete Guide to Creating a Unique Website Look from Scratch。
/*
Theme Name: My First Theme
Theme URI: https://example.com/my-first-theme
Author: Your Name
Author URI: https://example.com
Description: 一个简单的入门级响应式WordPress主题。
Version: 1.0
License: GNU General Public License v2 or later
Text Domain: my-first-theme
*/Then, create the simplest one possible.index.phpThe file, for now, only contains an HTML skeleton and the sentence “Hello World”.
<!DOCTYPE html>
<html no numeric noise key 1004>
<head>
<meta charset="<?php bloginfo( 'charset' ); ?>">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body no numeric noise key 1001>
<h1>This is my first theme.</h1>
</body>
</html>Now, log in to your WordPress backend and in the “Appearance” -> “Themes” section, you should be able to see “My First Theme” appear and enable it. Although it's currently quite basic, you've successfully created a theme that can be recognized by WordPress.
\n Construct the core template file of the theme
A complete theme consists of a series of template files, which control the display of different parts of the website. Let's start building it with the most important files first.
Separate the header from the footer
The first step is to separate the duplicate code (such as the header and footer) into separate files. Createheader.phpThe document, which contains information from...<!DOCTYPE html>To open<body>All the content before the tag.
<!DOCTYPE html>
<html no numeric noise key 1006>
<head>
<meta charset="<?php bloginfo( 'charset' ); ?>">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="profile" href="https://gmpg.org/xfn/11">
</head>
<body no numeric noise key 1003>
<header id="masthead" class="site-header">
<h1 class="site-title"><a href="/en/</?php echo esc_url( home_url( '/' ) ); ?>"></a></h1>
</header>Createfooter.phpThe file contains footer content and an ending tag.
Recommended Reading Create your own WordPress theme from scratch: a comprehensive guide to architecture, design, and development。
<footer id="colophon" class="site-footer">
<p>©</p>
</footer>
</body>
</html>Then, modify yourindex.phpDocument, useget_header()andget_footer()Use a function to incorporate these parts.
<main id="primary" class="site-main">
<?php
if ( have_posts() ) :
while ( have_posts() ) .
the_post();
// The article content will be displayed here
the_title( '<h2>', '</h2>' );
the_content();
endwhile.
else :
echo '<p>No content found.</p>'; endif.
</p>'; endif;
? >endif; ?
</main>Create an article loop and a sidebar
The aboveindex.phpIt already includes the basic WordPress main loop (The Loop), which is used to retrieve and display a list of articles. Next, createsidebar.phpLet's add a sidebar.
<aside id="secondary" class="widget-area">
<?php dynamic_sidebar( 'sidebar-1' ); ?>
</aside>In order to introduce a sidebar on the page, you need toindex.phpAdjust the structure of the main content area and useget_sidebar()A function. At the same time, you need to create one.functions.phpYou need to register this sidebar widget area with the corresponding files.
Implementing responsive layout and styling
Responsive design ensures that your theme displays well on a variety of devices. We will start with the basic CSS structure and media queries.
Setting basic styles and the flexible box model
In yourstyle.cssBelow the topic information annotation, add a reset style and basic layout. Using Flexbox to create a simple responsive layout is a good starting point.
/* 基础重置与样式 */
* {
box-sizing: border-box;
margin: 0;
padding: 0;
}
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
line-height: 1.6;
color: #333;
background-color: #fff;
}
/* 主要布局容器 */
#page {
display: flex;
flex-direction: column;
min-height: 100vh;
}
.site-main {
flex: 1;
padding: 2rem;
}
/* 头部与底部样式 */
.site-header, .site-footer {
background-color: #f8f9fa;
padding: 1rem 2rem;
text-align: center;
}Add a media query
Media queries are the core of responsive design. We add a simple breakpoint, and when the screen width is less than 768px (typically for tablet devices), the layout of the content area and sidebar changes from side-by-side to stacked.
Recommended Reading WordPress Theme Development: A Complete Guide from Beginner to Expert。
First of all, modify the HTML structure.index.phpIn Chinese, we use a container to wrap the main content and the sidebar.
<div class="content-area">
<main id="primary" class="site-main">
<!-- 主循环内容 -->
</main>
<?php get_sidebar(); ?>
</div>Then, add the corresponding styles in CSS.
.content-area {
display: flex;
flex-wrap: wrap;
}
.site-main {
flex: 3;
min-width: 300px;
}
#secondary {
flex: 1;
min-width: 250px;
padding-left: 2rem;
}
/* 响应式断点：平板及以下 */
@media (max-width: 768px) {
.content-area {
flex-direction: column;
}
#secondary {
padding-left: 0;
padding-top: 2rem;
}
.site-header, .site-footer, .site-main {
padding: 1rem;
}
}Enhance the theme's functionality through functions.php
functions.phpThe file is the “engine room” of your theme, used to add functionality, register features, and safely introduce scripts and styles.
Register the navigation menu and the gadget area.
Infunctions.phpIn Chinese, we useregister_nav_menusThe function is used to register the navigation menu location of the theme.
esc_html__( 'Primary Menu', 'my-first-theme' ),
'footer' => esc_html__( 'Footer Menu', 'my-first-theme' ),
) );
// Register sidebar widget areas
register_sidebar( array(
'name' => esc_html__( 'Main Sidebar', 'my-first-theme' ),
'id' => 'sidebar-1',
'description' => esc_html__( 'Add widgets here.', 'my-first-theme' ),
'before_widget' => '<section id="%1$s" class="widget %2$s">',
'after_widget' => '</section>',
'before_title' => '<h3 class="widget-title">',
'after_title' => '</h3>',
) );
}
add_action( 'after_setup_theme', 'my_first_theme_setup' );
?>After registering, you will be able toheader.phpandfooter.phpUse it in Chinesewp_nav_menu()Now, we can use the function to call these menus.
\nSecure loading styles and scripts
Never directly create hard links to CSS or JavaScript files within template files. Instead, you should use other methods to include those files.wp_enqueue_style()andwp_enqueue_script()The function, and throughwp_enqueue_scriptsUse hooks to load them.
function my_first_theme_scripts() {
// 加载主样式表
wp_enqueue_style( 'my-first-theme-style', get_stylesheet_uri(), array(), wp_get_theme()->get( 'Version' ) );
// 加载一个自定义JavaScript文件（如果需要）
wp_enqueue_script( 'my-first-theme-navigation', get_template_directory_uri() . '/js/navigation.js', array(), wp_get_theme()->get( 'Version' ), true );
}
add_action( 'wp_enqueue_scripts', 'my_first_theme_scripts' );Create more template files to enhance the functionality
At present, we only have one themeindex.phpIt will be used on all pages. The WordPress template hierarchy determines that it will look for more specific templates for different types of pages. Let's create some of them.
A single article and a page template
Createsingle.phpIt is used to display a single article.
<?php get_header(); ?>
<main id="primary" class="site-main">
<?php
while ( have_posts() ) :
the_post();
get_template_part( 'template-parts/content', 'single' );
// 显示文章导航
the_post_navigation();
// 如果评论开启，则加载评论模板
if ( comments_open() || get_comments_number() ) :
comments_template();
endif;
endwhile;
?>
</main>
<?php get_sidebar(); ?>
<?php get_footer(); ?>Createpage.phpIt is used to display static pages. Its structure is similar to that of a webpage.single.phpIt's similar, but it usually doesn't display meta information such as categories and tags.
In order to follow the DRY (Don't Repeat Yourself) principle, we can extract the content display section of articles and pages into template parts. Create a template part in the root directory of the theme.template-partsCreate a folder and then create something (or files) inside it.content-single.phpandcontent-page.php。
Article archive page template
Createarchive.phpIt is used to display archived pages such as categories, tags, and authors. It can be reused.index.phpThis is a loop in the middle, but usually, the archive title will be displayed at the top.
<main id="primary" class="site-main">
<header class="page-header">
<?php
the_archive_title( '<h1 class="page-title">', '</h1>' );
the_archive_description( '<div class="archive-description">', '</div>' );
?>
</header>
<?php
if ( have_posts() ) :
while ( have_posts() ) :
the_post();
get_template_part( 'template-parts/content', get_post_type() );
endwhile;
the_posts_navigation(); // 显示上一页/下一页导航
else :
get_template_part( 'template-parts/content', 'none' );
endif;
?>
</main>summarize
Through this guide, you have completed the setup of a basic but complete responsive WordPress theme. You have learned about the basic file structure of the theme, learned to separate template components (header, footer, sidebar), implemented the core WordPress loop, and used CSS media queries to build a responsive layout. In addition, you have mastered how to create a responsive layout by usingfunctions.phpUse the provided files to register menus, widgets, and methods for securely loading resources, and begin exploring WordPress's powerful template hierarchy system.
Theme development is an ongoing process. Next, you can explore more template files (such as404.php、search.php), learn to use WordPress's Body Class and Post Class to increase the granularity of style control, conduct in-depth research on the Customizer API to provide users with visual setting options, and even try to integrate modern front-end workflows such as Sass or ES6 into your development process.
FAQ Frequently Asked Questions
What are the minimum files required for a WordPress theme?
A minimal theme that can be recognized by WordPress only requires two files:style.cssandindex.php。style.cssThe header of the email must include the correct subject information annotation, andindex.phpThen, it will be used as the default template for all pages.
How can I make my theme support multi-language translation?
You need to do two things well. Firstly, you should...style.cssThe header comments and all instances where the text is used (for example, through…)__()Or_e()The function uses a text domain. In this guide, we use the text domain “my-first-theme”. Secondly, we use tools like Poedit to create a .pot file, and translate it into .po and .mo files, placing them in the theme's folder./languagesUnder the directory. Finally, infunctions.phpUse it in Chineseload_theme_textdomain()Function loading translation.
Why aren’t my custom styles or scripts taking effect?
This is usually because it's not loading in the order recommended by WordPress. Please make sure that you are doing it in the correct order.functions.phpIn the file, use…wp_enqueue_style()andwp_enqueue_script()Define the functions and mount them towp_enqueue_scriptsAdd styles and scripts to the hook. Links written directly in the template file may be ignored by caching plugins or loaded in the wrong order in some cases.
How to add custom logo support to my theme?
This is a very common feature. You need to...functions.phpIn the function for setting the file's theme settings (via…)after_setup_theme(After the hook executes), addadd_theme_support( 'custom-logo' )You can pass in an array of parameters to define the size and other properties of the Logo. Once these parameters are set, users can upload the Logo in the “Appearance” -> “Custom” -> “Site Identity” section. On the front end, you can use these parameters to display or apply the Logo accordingly.the_custom_logo()Use a function to display it.
How to debug PHP errors during the development process?
It is recommended to do this in the local development environment.wp-config.phpEnabling the WordPress debug mode in the file. Set the value of the 'WP_DEBUG' constant to 'true' in the wp-config.php file.WP_DEBUGThe constant is set totrueYou can also set it up at the same timeWP_DEBUG_LOGandWP_DEBUG_DISPLAYTo control whether errors are recorded in the log file or displayed on the screen. Remember to turn off debug mode before putting the theme online.
What's next, what's next?
Extended reading and practical knowledge
The following are related to the topic of this article and are suitable for further in-depth reading. Prioritize starting with the article that is closest to your current problem, and gradually expanding to surrounding topics usually works better.
- WordPress Theme Development from Scratch: Creating a Unique Website Interface
- WordPress Theme Development Guide: Building Custom Websites from Scratch
- WordPress Theme Development Complete Guide: A Practical Tutorial from Scratch to Mastery
- Complete Guide to WordPress Theme Development: Building Professional-Level Website Templates from Scratch
- WordPress Theme Development in Action: Building Responsive Enterprise-Level Websites from Scratch
English