Home/knowledge-related/WordPress/Content Details

Introduction to WordPress Theme Development: Building Your First Theme from Scratch

4-minute read
2026-03-15
2026-06-04
2,082
I earn commissions when you shop through the links below, at no additional cost to you.

Preparatory work and environment setup

Before you start writing any code, you need a suitable development environment. This includes a local server environment (such as XAMPP, Local by Flywheel, or MAMP) and a code editor (such as VS Code, Sublime Text, or PHPStorm). Make sure your local environment has PHP, MySQL, and Apache/Nginx installed.

Next, you need to configure the local server.wp-content/themes/Create a new folder under the directory. The name of this folder will be your theme name, for examplemy-first-themeThis is the “home” of all your theme files.

A basic WordPress theme only requires two files:style.cssandindex.phpAmong them,style.cssIt's not just a style sheet, but also a “identity card” for the theme. The annotation block at the top of it contains the meta information of the theme. Let's create this file first.

Recommended Reading Learning WordPress theme development from scratch: A complete guide to creating a personalized website。

Create a theme information header file

style.cssThe comment block at the top of the file is key for WordPress to identify a theme. Please create it in your theme folder.style.cssAnd enter the following content:

UltaHost WordPress Hosting
30-day refund guarantee, unlimited bandwidth and database usage, free DDoS protection; purchase for 3 years and get a discount of 50%.
UltaHost LOGO access page 
/*
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
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Text Domain: my-first-theme
*/

These information will be displayed on the “Appearance” -> “Themes” page in the WordPress backend.Text DomainIt is used for internationalization and is a key identifier for loading translation files subsequently.

Create a basic index template

Next, create the core file of the themeindex.phpEven if this file only contains one line of code for the time being, it can still allow WordPress to recognize and activate your theme.

<h1>Hello, WordPress Theme World!</h1>

get_header()andget_footer()These are template functions of WordPress, which will attempt to load a file namedheader.phpandfooter.phpAlthough we haven't created them yet, it's standard practice to write them this way first. Now, you can go to the WordPress backend, find and activate “My First Theme” in “Appearance” -> “Themes”. Refresh the website homepage, and you will see the sentence “Hello, WordPress Theme World!”.

Understand the template hierarchy and create the core files

WordPress uses a set of rules called the “template hierarchy” to determine which template file should be used to present content for different page requests (such as the homepage, article page, and category page). Understanding this mechanism is the foundation for efficient theme development.

Recommended Reading Introduction to WordPress Theme Development: Create Your First Custom Theme Step by Step。

The most commonly used template isindex.phpIt's the final option for all pages. However, to control the appearance of different pages more precisely, we should create more specific template files. First, let's create three basic and important files:header.php、footer.phpandfunctions.php。

Build the website header template

header.phpFiles usually contain the header of an HTML document.<head>And the public areas at the top of the website, such as the logo and navigation menu. Create oneheader.phpFile:

<!DOCTYPE html>
<html no numeric noise key 1007>
<head>
    <meta charset="<?php bloginfo( 'charset' ); ?>">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    
</head>
<body no numeric noise key 1004>
    <header id="site-header">
        <div class="container">
            <h1><a href="/en/</?php echo esc_url( home_url( '/' ) ); ?>"></a></h1>
            <p></p>
            <nav>
                <p><strong>Output:</strong>  
 'primary',  
    'menu_id' =&gt; 'primary-menu',  
) );  
?&gt;  
</p>
            </nav>
        </div>
    </header>
    <main id="main-content">

There are several key functions here:wp_head()Hooks allow WordPress core, plugins, and themes to interact with each other.<head>Insert the necessary code (such as the link to the style sheet) into the area;body_class()It will output a series of CSS class names, making it convenient for you to control the styles according to different pages;wp_nav_menu()It is used to display a navigation menu.

hosting.com Shared Hosting
High performance with AMD EPYC CPUs, NVMe SSD storage and LiteSpeed, 24/7, 24x7 expert in-house support, advanced security measures including SSL, brute force, malware and DDoS protection, savings of up to 73%
hosting.com LOGO access page

Build the bottom template of the website

footer.phpThe file usually contains the public bottom area of the website, such as copyright information, and closes after being viewed.header.phpThe tab that opens in the middle. Createfooter.php：

    </main><!-- #main-content -->
    <footer id="site-footer">
        <div class="container">
            <p>©  . All rights reserved.</p>
        </div>
    </footer>
    
</body>
</html>

wp_footer()andwp_head()Similarly, it is an important hook used to...</body>Insert the script or code before the tag.

Now, let's get back to yourindex.phpUpdate it to use our newly created header and footer files:

Recommended Reading How to choose and customize an SEO-friendly WordPress theme。

<!php get_header(); ?>  
<!php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
    <article>
        <h2></h2>
        <div>\n</div>
    </article>

    <p><?php esc_html_e( 'Sorry, no posts matched your criteria.', 'my-first-theme' ); ?></p>

This code forms the core loop (The Loop) of the WordPress theme, which checks whether there are any articles on the current page and then iteratively outputs the title and content of each article.

Enhance the theme functionality through function files

functions.phpIt is the “control center” of your theme. It's not a template file, but a PHP file that is automatically loaded when the theme is initialized. You can add theme support functions, register menu locations, queue stylesheets and scripts, etc. here. Createfunctions.php：

InterServer Shared Hosting
Shared hosting $2.50 USD per month , first month $0.1 USD promo code tryinterserver, 461 cloud apps scripts, one click install.
InterServer LOGO access page 
<?php
/**
 * My First Theme 的功能函数文件
 */

// 主题基础设置
if ( ! function_exists( 'my_first_theme_setup' ) ) :
    function my_first_theme_setup() {
        // 让WordPress管理文档标题
        add_theme_support( 'title-tag' );
        // 启用文章和页面的特色图片功能
        add_theme_support( 'post-thumbnails' );
        // 注册一个主导航菜单
        register_nav_menus( array(
            'primary' => esc_html__( 'Primary Menu', 'my-first-theme' ),
        ) );
        // 为文章摘录添加HTML支持
        add_filter( 'excerpt_more', 'my_first_theme_excerpt_more' );
    }
endif;
add_action( 'after_setup_theme', 'my_first_theme_setup' );

// 修改摘录末尾的“更多”链接样式
function my_first_theme_excerpt_more( $more ) {
    return '...';
}

// 注册并加载样式表
function my_first_theme_scripts() {
    // 加载主样式表
    wp_enqueue_style( 'my-first-theme-style', get_stylesheet_uri() );
    // 加载一个自定义样式表
    wp_enqueue_style( 'my-first-theme-custom-style', get_template_directory_uri() . '/assets/css/custom.css', array(), '1.0' );
}
add_action( 'wp_enqueue_scripts', 'my_first_theme_scripts' );

This function file accomplishes several important tasks: 1) Byadd_theme_support()1) Enabled the commonly used features of modern WordPress themes; 2) Throughregister_nav_menus()We registered a WeChat mini program so that we could easily manage our orders and payments.header.phpThe function called in the middleprimary1) First, the menu needs to be assigned in the “Appearance” -> “Menu” section in the backend; 3) Then, it can be used.wp_enqueue_style()The function correctly adds the stylesheet to the queue in a secure and reliable manner.

Create an independent article template

In order to enhance the display effect of a single article, we can create a dedicated template filesingle.phpAccording to the template hierarchy, when accessing a single article, WordPress will prioritize usingsingle.phpInstead ofindex.php。

<article id="post-<?php the_ID(); ?>" no numeric noise key 1007>
    <header class="entry-header">
        &lt;?php the_title( &#039;<h1 class="entry-title">', '</h1>' ); ?&gt;
        <div class="entry-meta">
            
        </div>
        <?php if ( has_post_thumbnail() ) : ?>
            <div class="post-thumbnail">
                <?php the_post_thumbnail( 'large' ); ?>
            </div>
        
    </header>
    <div class="entry-content">
        \n
    </div>
</article>

This template provides a more detailed display of article information, such as the publication date and featured image (if set).post_class()The function will output CSS classes specific to the article type.

Add basic styles and responsive design

Now that your theme has a basic structure and functionality, it's time to make it look good. We will proceed tostyle.cssAdd some basic CSS to the page and ensure that it has a responsive design.

In yourstyle.cssAdd the following style to the document (below the subject header):

/* 基础重置与排版 */
* {
    box-sizing: border-box;
    margin: 0;
    padding: 0;
}
body {
    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
    line-height: 1.6;
    color: #333;
    background-color: #f9f9f9;
}
.container {
    width: 100%;
    max-width: 1200px;
    margin: 0 auto;
    padding: 0 20px;
}

/* 头部样式 */
#site-header {
    background: #fff;
    border-bottom: 1px solid #eee;
    padding: 1rem 0;
}
#site-header h1 a {
    color: #333;
    text-decoration: none;
}

/* 导航菜单 */
#primary-menu {
    display: flex;
    list-style: none;
}
#primary-menu li {
    margin-right: 1rem;
}
#primary-menu a {
    text-decoration: none;
    color: #555;
}

/* 主内容区 */
#main-content {
    padding: 2rem 0;
}
article {
    background: #fff;
    padding: 2rem;
    margin-bottom: 2rem;
    border-radius: 4px;
    box-shadow: 0 2px 4px rgba(0,0,0,0.05);
}

/* 底部样式 */
#site-footer {
    background: #333;
    color: #fff;
    text-align: center;
    padding: 1.5rem 0;
    margin-top: 2rem;
}

/* 响应式设计 */
@media (max-width: 768px) {
    .container {
        padding: 0 15px;
    }
    #primary-menu {
        flex-direction: column;
    }
    #primary-menu li {
        margin-right: 0;
        margin-bottom: 0.5rem;
    }
    article {
        padding: 1rem;
    }
}

These styles provide a clear and modern visual effect, and offer a basic responsive layout on small-screen devices. You can create/assets/css/custom.cssWe can use the "Style" folder to store more custom styles, which have already been created in the "Style" folder.functions.phpThey were lined up to load their luggage onto the bus in China.

summarize

Following the steps in this article, you have successfully built a fully functional and well-structured WordPress theme starting from an empty folder. You have learned about the most basic files involved in theme development.style.cssandindex.phpAfter learning about the concept of template levels, I created a template.header.php、footer.php、single.phpAnd other core template files. You can also do it throughfunctions.phpThe file adds functional support and resource management capabilities to your theme, and finally gives it visual life through CSS.

This is just a starting point. Next, you can explore creating more template files (such aspage.php、archive.php、404.php(Note: The original text contains a typo, where "hook" should be translated as "Hooks" and "action" should be translated as "Actions/Filters". The corrected version is provided below.) To become a proficient WordPress theme developer, you need to deeply study the WordPress Hooks and Actions/Filters system, and explore how to enable your theme to support widgets and the Customizer. Through constant practice and exploration, you will achieve this goal.

FAQ Frequently Asked Questions

How to modify the logo of a theme?

Inheader.phpIn the file, find the code line that displays the website title. You can use a `<` to do this.

\n`Tag replacementbloginfo( ‘name’ )And link to your logo image. A more professional approach would be to...functions.phpUse it in Chineseadd_theme_support( ‘custom-logo’ )To support the logo upload function in the WordPress customizer.

Why isn't my navigation menu showing up?

First, please make sure that you have alreadyfunctions.phpPassed in the middleregister_nav_menus()Registered a takeout location (for example,primaryNext, you need to log in to the WordPress backend and go to the “Appearance” -> “Menus” page. Create a new menu, select the menu items, and check the menu location you registered (such as “Primary Menu”) in the “Display Location” area. Finally, save the menu.

How to add a sidebar to a theme?

Firstly, infunctions.phpUse it in Chineseregister_sidebar()The function registers a sidebar widget area. Then, in the template file where you want to display the sidebar (such as ), you can use the following code to display the sidebar:index.phpOrsingle.phpIn this document, we usedynamic_sidebar()This is the area for function calls. At the same time, you need to createsidebar.phpThe file is used to define the specific HTML structure of the sidebar.

Do the operations in the functions.php file have to be mounted with hooks?

Yes, in most cases, to ensure that the code is executed at the right time, you should wrap the functional code in a function and use specific hooks, such asafter_setup_theme、wp_enqueue_scriptsMount it. Just write it directly.functions.phpGlobal-scope code may execute at an inappropriate time or cause errors.

What's next, what's next?

If you are building or optimizing a WordPress website, the next step is to continue reading about performance optimization, plugin configuration, and theme customization.

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.

Tags.