How to Build Your First Wordpress Theme

A WordPress theme controls how your content is displayed. Building one means writing template files that WordPress selects according to a defined hierarchy, plus a stylesheet and a functions file that registers what the theme supports.

Before writing any of it, the more valuable decision is which of three routes you actually need — because most people who set out to build a theme would be better served by one of the other two.

Build, customise, or configure?

Approach	Suits	Effort
Configure a block theme	Most sites. Layout and styling handled in the editor and theme.json, no PHP	Low
Child theme of an existing theme	You need a parent theme's behaviour with specific changes, and want its updates	Moderate
Custom theme from scratch	Genuinely bespoke requirements, or you need full control of markup and performance	High

The honest guidance: build from scratch when you have a specific reason. "The available themes are not quite right" is usually solved by a child theme or by theme.json configuration, in a fraction of the time and with a fraction of the maintenance burden.

Classic themes and block themes

WordPress has two theme architectures, and knowing which you are working with determines everything else.

Classic themes

The traditional approach. PHP template files — index.php, single.php, archive.php — output markup using template tags and the loop. Styling comes from a stylesheet. Layout is defined in PHP.

Still entirely valid, still widely used, and still the right choice when you need precise control over markup or are working with an existing classic codebase.

Block themes

Introduced with full site editing in WordPress 5.9. Templates are HTML files composed of blocks rather than PHP, stored in a templates/ directory. Global styles, colour palettes, typography and spacing are declared in theme.json. Site editors can then change headers, footers and templates through the interface without touching code.

For a new project where the client will maintain the site, block themes are usually the better answer — they hand over genuine control rather than requiring a developer for layout changes.

Which to learn

If you are starting now, learn block themes and theme.json first, then classic templating when you encounter an older codebase. If you maintain existing classic themes, there is no urgency to convert working sites — classic themes remain supported.

The template hierarchy

This is the concept that makes WordPress theming comprehensible, and the one most tutorials rush past.

When WordPress renders a URL, it works out what kind of content is being requested and then looks for template files in a defined order, using the first one it finds. A single blog post looks for single-post.php, then single.php, then singular.php, then index.php.

index.php is the universal fallback — a theme containing only that file will render every page type. Everything else is a more specific override.

The practical consequence: you do not need many template files. Start with a fallback and add specific templates only where a page type genuinely needs to differ. Themes with forty template files that mostly duplicate each other are a maintenance problem created by copying a starter theme without pruning it.

The full hierarchy is documented and worth keeping open while you work.

Building a minimal classic theme

A functioning classic theme needs remarkably little.

The required files

• style.css — must open with a comment block declaring the theme name, which is how WordPress identifies it
• index.php — the fallback template

That is genuinely the minimum. In practice you also want:

• functions.php — registers theme support, enqueues assets, registers menus and widget areas
• header.php and footer.php — shared markup, included via get_header() and get_footer()
• single.php and page.php — individual posts and pages
• screenshot.png — the preview image in the admin

The loop

Every template that displays content runs the loop — WordPress's mechanism for iterating over the posts matching the current query. It is the single most important pattern in classic theming, and understanding that the query is determined by the URL before your template runs explains most confusing behaviour.

functions.php

This file is where a theme declares what it supports and loads its assets.

Two rules matter more than the rest. Enqueue scripts and styles properly using WordPress's enqueue functions rather than hard-coding tags into the header — this lets WordPress manage dependencies and load order, and it is what other plugins expect. And prefix everything; function names live in a global namespace shared with every plugin, and a generic function name will eventually collide with something.

Customising an existing theme

Most theme work is modification rather than creation, and there is a right way to do it.

Never edit the parent theme directly

Changes made to a theme's files are erased the next time it updates. This is the single most common WordPress mistake, and it is usually discovered months later when an update wipes work nobody documented.

Use a child theme

A child theme is a separate theme that inherits from a parent. It needs only a style.css declaring the parent in a Template: header, plus a functions.php to enqueue styles.

Once active, any template file you place in the child overrides the parent's version of that file, and the child's functions.php runs in addition to the parent's. You change what you need and inherit everything else, including updates.

Two things to know. Child theme functions.php files are additive, not overriding — you cannot replace a parent function by redeclaring it unless the parent wrapped it in function_exists(). And overriding a template file means you now maintain it: if the parent improves that file in a later release, your copy does not receive the change.

For block themes

Much customisation happens without code at all — through the site editor and through theme.json, which defines colour palettes, typography scales, spacing and layout constraints in one place. A child theme with only a theme.json can substantially restyle a parent without touching a template.

Setting up to develop

Theme work is far less painful with a few things in place before you start.

A local environment

Develop locally rather than on a live site. Several tools install a full WordPress stack on your machine in minutes. Editing a production theme through the admin file editor — which WordPress still offers — is how sites get taken down by a stray syntax error, since a fatal error in a theme file can leave you unable to reach the admin to undo it.

Disable the file editor entirely on client sites by setting DISALLOW_FILE_EDIT in wp-config.php. It removes a genuine risk and nobody misses it.

Debugging turned on

Set WP_DEBUG to true locally, and log errors to a file rather than displaying them. Developing with errors suppressed means shipping notices and deprecations you never saw — and deprecation warnings are how you learn a function is going away before it does.

Version control from the first commit

Track the theme directory in Git. Themes accumulate changes from multiple people over years, and "which version was working" is otherwise unanswerable. Exclude WordPress core and uploads; track only what you author.

A starter theme, pruned

Starting from a minimal starter theme is reasonable, provided you delete what you do not use. The common failure is inheriting forty template files and a large stylesheet, keeping all of it, and maintaining code nobody understands. If you cannot explain why a file exists, remove it and see what breaks — locally.

Mistakes that cause real problems

Editing theme or core files directly. Lost at the next update.

Putting functionality in the theme. Custom post types, shortcodes and business logic belong in a plugin. Anything in the theme disappears when the theme is switched, and switching themes should not delete a client's content structure.

Not escaping output. Every dynamic value printed to the page should be escaped with the appropriate function. Unescaped output is the most common source of cross-site scripting vulnerabilities in themes.

Not sanitising input. Anything accepted from a user or a setting field must be validated and sanitised before use.

Hard-coding URLs. Use the appropriate WordPress functions so the theme survives moving between staging and production.

Loading assets everywhere. A script needed by one template should be enqueued conditionally, not on every page.

Ignoring accessibility. Semantic markup, a skip link, visible focus states, and headings in a sensible order are theme responsibilities, and retrofitting them later is far more work.

Performance is a theme decision

Themes are responsible for much of what determines whether a WordPress site is fast.

• Limit web fonts. Each weight is a file. Self-host where practical.
• Set image dimensions so the layout does not shift as they load.
• Do not lazy-load the main image on a page — it delays the largest paint.
• Avoid bundling large libraries for one small effect.
• Keep database queries in templates minimal; a custom query inside a loop is a common cause of slow archive pages.

A well-built theme on modest hosting outperforms a heavy theme on expensive hosting. Theme choice is usually the larger factor.

Two habits keep a theme fast as it grows. Audit what you enqueue periodically — assets added for a feature that was later removed tend to stay loaded for years. And measure on a page with real content rather than a near-empty test page, because the queries that slow an archive only appear once there is something to query.

Keep translation in mind from the start

Wrap user-facing strings in WordPress's translation functions with a consistent text domain, even if you have no plans to translate. It costs nothing while writing and is tedious to retrofit across a finished theme. It also makes the theme usable by anyone who later needs it in another language, which for an agency building on the same base repeatedly is a genuine saving.

Testing a theme before it goes live

Themes fail in ways that are invisible on the developer's own content, because the developer tests with three tidy posts and the client has four hundred messy ones.

Test with realistic content

Use content that resembles what the site will actually hold: very long titles, posts with no featured image, categories containing one item and categories containing two hundred, deeply nested comment threads, tables pasted from a spreadsheet, and an author with no biography. Every one of these breaks themes that looked fine in development.

The WordPress community maintains theme unit test data for exactly this purpose — a set of deliberately awkward posts that exercise the edge cases. Importing it takes minutes and surfaces problems that would otherwise appear after launch.

Check the pages nobody designs

Search results, the 404 page, paginated archives, category and tag archives, and the author page are all rendered by your theme and all routinely forgotten. A 404 page inheriting a broken layout is a poor first impression for someone who already failed to find something.

Verify the editor experience

The site is only half the deliverable; the other half is whether the client can use it. Log in as a non-administrator and try to publish a post, add an image, and change a menu. Themes that assume developer-level knowledge produce clients who are afraid to touch their own site.

Build or buy?

An honest assessment, since the answer is often buy.

A well-chosen existing theme makes sense when your requirements are conventional, you want ongoing updates and security fixes maintained by someone else, and the budget is better spent on content and marketing than on bespoke templates. Configuring a good block theme through theme.json and the site editor covers a great many business sites completely.

A custom theme makes sense when you have genuinely unusual layout or functional requirements, when performance is critical enough that removing unused code matters, when brand differentiation is commercially significant, or when you are integrating with systems no theme anticipates.

The maintenance question decides it more often than the build cost. A custom theme is yours to update, secure and fix indefinitely. That is a real ongoing commitment, and it should be a deliberate one rather than a consequence of preferring to build.

WordPress itself is not always the right platform either — worth understanding why businesses build on WordPress and, equally, where WordPress struggles, before committing to theme work at all.

Frequently asked questions

What is WordPress theme development?

Building the files that control how WordPress displays content — template files selected by the template hierarchy, a stylesheet, and a functions file registering what the theme supports. Modern block themes use HTML templates and a theme.json configuration file instead of PHP templates for much of this.

How do I customise a theme in WordPress?

Create a child theme rather than editing the parent, because direct edits are erased at the next update. A child theme needs a style.css declaring the parent and a functions.php to enqueue styles; any template file you add to it overrides the parent's version. For block themes, much customisation happens through theme.json and the site editor without code.

Should I build a custom WordPress theme or use an existing one?

Use an existing theme unless you have a specific reason not to. Custom themes make sense for genuinely unusual requirements, critical performance, or significant brand differentiation. The deciding factor is usually maintenance: a custom theme is yours to secure and update indefinitely.

What is the difference between a classic theme and a block theme?

Classic themes use PHP template files and define layout in code. Block themes use HTML templates composed of blocks, with styling declared in theme.json, and allow site owners to edit headers, footers and templates through the editor. Block themes generally hand more control to the client; classic themes give developers more precise control of markup.

Do I need to know PHP to build a WordPress theme?

For classic themes, yes. For block themes, much less — a substantial block theme can be built with HTML templates and theme.json alone. Some PHP is still useful for anything beyond presentation, but it is no longer the entry requirement it once was.

Where to start

Build a minimal classic theme first — style.css and index.php, nothing else — and watch it render your site. That exercise teaches the template hierarchy faster than reading about it, because you can then add one template at a time and see exactly what each one takes over.

Then build the same thing as a block theme with a theme.json. The comparison makes the trade-off between the two architectures concrete rather than theoretical.

Keep the Theme Handbook open while you work. WordPress theming has a great deal of accumulated convention, and most of the frustration people report comes from fighting those conventions rather than following them — the handbook is where they are written down.

If the requirement is a production theme rather than a learning exercise, our theme customisation services cover child-theme development and block theme configuration, including the maintenance side that custom work commits you to.