Building a WordPress theme from scratch is one of the best ways to understand how WordPress works. A theme controls every aspect of your site’s appearance and layout. While pre-built themes are convenient, custom theme development gives you complete control over the design, performance, and user experience.
This guide covers how to build a WordPress theme from scratch, from the essential files to advanced block theme features.
Essential Theme Files
Every WordPress theme needs at least two files: style.css and index.php. style.css contains the theme header — name, author, version, description — and any base CSS styles. index.php is the main template file that renders all pages by default if no more specific template exists.
For block themes, you need a theme.json file instead of (or in addition to) functions.php for styling configuration. A templates/index.html file replaces index.php as the primary template. Block themes are the future of WordPress theming and are required for full site editing support.
The Template Hierarchy
WordPress’s template hierarchy determines which template file is used to render each type of page. The hierarchy progresses from specific templates to general ones. For example, a single post uses single-post-{slug}.php, then single-post-{id}.php, then single.php, then singular.php, and finally index.php.
Understanding the template hierarchy lets you create precise templates for different content types. Create archive.php for archive pages, single.php for single posts, page.php for pages, and front-page.php for the homepage. Each template inherits from index.php if it doesn’t exist.
Template Tags and The Loop
The WordPress Loop is the core of template files. It processes the main query, displaying each post in turn. Within the loop, template tags like the_title(), the_content(), the_permalink(), and the_post_thumbnail() output post data. Outside the loop, template tags like wp_nav_menu(), get_sidebar(), and get_footer() render structural elements.
Template tags handle escaping automatically. Use the_title() instead of echoing get_the_title() directly. Use the_content() instead of applying content filters manually. These template tags are the standard WordPress way of rendering content.
Enqueuing Assets
Load CSS and JavaScript in your theme using wp_enqueue_style() and wp_enqueue_script(). Add these to a function hooked to wp_enqueue_scripts. Always use the proper dependency system — if your JavaScript requires jQuery, declare it as a dependency. Version your assets so browsers load new versions when you update the theme.
Register theme support features with add_theme_support() in functions.php. Common features include post-thumbnails, custom-logo, html5, title-tag, and align-wide. For block themes, configure these in theme.json instead.
Custom Page Templates
Custom page templates let you create unique layouts for specific pages. Create a PHP file with a Template Name header comment. The template appears in the Page Attributes meta box on page editing screens. Use custom page templates for landing pages, full-width layouts, or any page that needs a different structure from standard pages.
For block themes, custom templates are created as HTML files in the templates directory and registered through theme.json.
The Bottom Line
WordPress theme development follows a well-defined pattern. Start with the essential files, learn the template hierarchy, master the Loop and template tags, enqueue your assets properly, and create custom templates for special layouts. Block themes represent the future direction, but classic themes with PHP templates are still widely used and fully supported.