WordPress Theme Handbook vs Theme Developer Handbook

 

WordPress Theme Handbook vs Theme Developer Handbook

Both are official WordPress documentation, but you can think of them as one large learning resource organized around different aspects of theme development.

1. WordPress Theme Handbook

The is the main documentation for learning how WordPress themes work.

It covers topics such as:

• Theme structure

• Template files

• The WordPress Loop

• Template hierarchy

• functions.php

• CSS and JavaScript

• Theme features

• Navigation menus

• Featured images

• Custom templates

• Block themes

• Classic themes

• Theme development best practices

For a beginner, I recommend learning in this order:

Theme Basics
     ↓
Theme Structure
     ↓
style.css
     ↓
index.php
     ↓
header.php / footer.php
     ↓
functions.php
     ↓
The Loop
     ↓
Template Hierarchy
     ↓
Custom Templates

2. WordPress Theme Developer Handbook

The is essentially the developer-focused documentation within the WordPress theme documentation.

It goes deeper into how to actually build and develop themes, including the technical APIs and standards you'll

WordPress Theme Handbook vs Theme Developer Handbook

Both are official WordPress documentation, but you can think of them as one large learning resource organized around different aspects of theme development.

1. WordPress Theme Handbook

The is the main documentation for learning how WordPress themes work.

It covers topics such as:

• Theme structure

• Template files

• The WordPress Loop

• Template hierarchy

• functions.php

• CSS and JavaScript

• Theme features

• Navigation menus

• Featured images

• Custom templates

• Block themes

• Classic themes

• Theme development best practices

For a beginner, I recommend learning in this order:

Theme Basics
     ↓
Theme Structure
     ↓
style.css
     ↓
index.php
     ↓
header.php / footer.php
     ↓
functions.php
     ↓
The Loop
     ↓
Template Hierarchy
     ↓
Custom Templates

2. WordPress Theme Developer Handbook

The is essentially the developer-focused documentation within the WordPress theme documentation.

It goes deeper into how to actually build and develop themes, including the technical APIs and standards you'll use when creating professional themes.

For example:

<?php

function my_theme_setup() {

    add_theme_support('post-thumbnails');

    register_nav_menus(
        array(
            'primary' => 'Primary Menu'
        )
    );
}

add_action('after_setup_theme', 'my_theme_setup');

You can use the documentation to understand what add_theme_support(), register_nav_menus(), and add_action() actually do.

Which one should you use?

If you're learning WordPress theme development from the beginning, follow this path:

Step 1: Learn the basic concepts in the Theme Handbook.

Step 2: Build a small classic theme like the demo we created above.

Step 3: Learn the Template Hierarchy.

Step 4: Learn WordPress functions and hooks.

Step 5: Learn theme security and coding standards.

Step 6: Move into block themes and Full Site Editing.

Step 7: Build a complete professional theme.

A simple learning roadmap

HTML + CSS
    ↓
Basic PHP
    ↓
WordPress Basics
    ↓
Theme Structure
    ↓
index.php
    ↓
header.php + footer.php
    ↓
functions.php
    ↓
WordPress Loop
    ↓
Template Hierarchy
    ↓
Menus + Widgets + Featured Images
    ↓
Custom Templates
    ↓
Hooks + Filters
    ↓
Block Themes
    ↓
Professional WordPress Theme

In short: use the Theme Handbook as your main learning/reference guide, and use the developer-oriented sections when you need detailed technical information while building your theme.

Read More

How to Create a WordPress Theme: Build a Simple Demo Theme

 Creating a basic WordPress theme is a great way to learn PHP, HTML, CSS, and WordPress development. Below, we'll build a small working demo theme from scratch.

1. Create the theme folder

Go to:

wp-content/themes/

Create a folder:

my-demo-theme

Our final theme will look like this:

my-demo-theme/
├── style.css
├── index.php
├── functions.php
├── header.php
├── footer.php
└── single.php

---

2. Create style.css

Create:

style.css

Add the WordPress theme information at the top:

/*
Theme Name: My Demo Theme
Theme URI: https://example.com
Author: Your Name
Description: A simple beginner WordPress theme.
Version: 1.0
*/

body {
    margin: 0;
    font-family: Arial, sans-serif;
    background: #f5f5f5;
    color: #333;
}

.site-header {
    background: #222;
    color: white;
    padding: 30px;
    text-align: center;
}

.site-header a {
    color: white;
    text-decoration: none;
}

.site-content {
    max-width: 900px;
    margin: 30px auto;
    background: white;
    padding: 30px;
}

.site-footer {
    background: #222;
    color: white;
    text-align: center;
    padding: 20px;
}

The information at the top tells WordPress that this folder is a theme.

---

3. Create functions.php

Now create:

functions.php

Add:

<?php

function my_demo_theme_setup() {

    add_theme_support('title-tag');
    add_theme_support('post-thumbnails');

    register_nav_menus(
        array(
            'primary' => 'Primary Menu'
        )
    );
}

add_action('after_setup_theme', 'my_demo_theme_setup');

function my_demo_theme_styles() {

    wp_enqueue_style(
        'my-demo-theme-style',
        get_stylesheet_uri()
    );
}

add_action('wp_enqueue_scripts', 'my_demo_theme_styles');

This sets up basic theme features and loads our CSS file.

---

4. Create header.php

Create:

header.php

Add:

<!DOCTYPE html>
<html <?php language_attributes(); ?>>

<head>
    <meta charset="<?php bloginfo('charset'); ?>">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <?php wp_head(); ?>
</head>

<body <?php body_class(); ?>>

<header class="site-header">

    <h1>
        <a href="<?php echo esc_url(home_url('/')); ?>">
            <?php bloginfo('name'); ?>
        </a>
    </h1>

    <p><?php bloginfo('description'); ?></p>

</header>

<main class="site-content">

The important function here is:

wp_head();

WordPress and plugins use this hook to insert required information into the <head> section.

---

5. Create footer.php

Create:

footer.php

Add:

</main>

<footer class="site-footer">

    <p>
        &copy; <?php echo date('Y'); ?>
        <?php bloginfo('name'); ?>
    </p>

</footer>

<?php wp_footer(); ?>

</body>
</html>

wp_footer() is important because plugins and WordPress can use it to add scripts and other functionality before the closing </body> tag.

---

6. Create index.php

Now create the main template:

index.php

Add:

<?php get_header(); ?>

<h2>Latest Posts</h2>

<?php if (have_posts()) : ?>

    <?php while (have_posts()) : the_post(); ?>

        <article>

            <h2>
                <a href="<?php the_permalink(); ?>">
                    <?php the_title(); ?>
                </a>
            </h2>

            <p>
                <?php the_excerpt(); ?>
            </p>

        </article>

        <hr>

    <?php endwhile; ?>

<?php else : ?>

    <p>No posts found.</p>

<?php endif; ?>

<?php get_footer(); ?>

This is the famous WordPress Loop.

The basic idea is:

while (have_posts()) {
    the_post();
}

WordPress uses the Loop to display posts.

---

7. Create single.php

Create:

single.php

Add:

<?php get_header(); ?>

<?php if (have_posts()) : ?>

    <?php while (have_posts()) : the_post(); ?>

        <article>

            <h1><?php the_title(); ?></h1>

            <p>
                Published on:
                <?php echo get_the_date(); ?>
            </p>

            <?php the_content(); ?>

        </article>

    <?php endwhile; ?>

<?php endif; ?>

<?php get_footer(); ?>

This template displays an individual blog post.

---

8. Activate your theme

Go to your WordPress dashboard:

Appearance → Themes

You should see:

My Demo Theme

Click:

Activate

Now visit your website.

You have a working custom WordPress theme. 🎉

---

9. Create a demo post

Go to:

Posts → Add New

Create a post such as:

Welcome to My Demo Theme

Add some sample content:

This is my first post using a custom WordPress theme. I created this theme from scratch using PHP, HTML, and CSS.

Click Publish.

Return to your homepage and you should see the post.

---

10. How the theme works

The basic flow is:

WordPress
   ↓
index.php
   ↓
get_header()
   ↓
header.php
   ↓
WordPress Loop
   ↓
Post content
   ↓
get_footer()
   ↓
footer.php

The important files are:

File	Purpose
style.css	Theme information + CSS
functions.php	Theme functionality
header.php	Website header
footer.php	Website footer
index.php	Main fallback template
single.php	Individual blog posts

Your first theme is now complete

Your folder should contain:

my-demo-theme/
│
├── style.css
├── functions.php
├── header.php
├── footer.php
├── index.php
└── single.php

This is a classic WordPress theme. It's intentionally simple so you can understand how WordPress themes work before moving on to more advanced topics such as page.php, archive.php, custom post types, template parts, widgets, customizer settings, and the WordPress REST API.

Read More