How to Build a WordPress Theme Using Underscores

Building a WordPress theme starts with choosing a foundation that fits the kind of theme you plan to make. Underscores, also called _s, is a starter for classic WordPress themes that gives developers files to adapt into a custom design.

This article explains where _s fits today and shows how to generate and check a starter before activating it.

TL;DR

Underscores (_s) can still serve as a base for a classic PHP theme, but Automattic archived its repository in September 2025 and says it will not be actively updated. For a new block theme, start with the WordPress Site Editor or the Create Block Theme plugin instead.

  • Choose _s when your task specifically needs a classic PHP theme or you are maintaining an existing one.
  • Use WP-CLI’s wp scaffold underscores command or the generator for an _s-based theme, then change its identifiers and test it locally.
  • Choose a block theme for a new project that should use block templates and the Site Editor.

What Is Underscores for WordPress?

Underscores, also written as _s, is a starter for classic WordPress themes, supplying PHP templates, theme functions, JavaScript, and starter styles for developers adapting files into a custom design.

Automattic’s _s repository is inactive and archived for reference. The WP-CLI handbook documents scaffolding, but the command does not make the generated code actively maintained.

A classic theme renders a request through PHP templates such as index.php, single.php, and functions.php. A block theme instead stores block markup in files such as templates/index.html, with site owners able to edit templates in the Site Editor.

ChooseTheme files and workflowGood fit
UnderscoresClassic PHP templates, functions.php, CSS and optional JavaScriptMaintaining a classic theme or learning its PHP template flow
Block themestyle.css, theme.json, templates/index.html, Site EditorStarting a theme designed for block editing

How to Use Underscores Step by Step

For a classic-theme project, generate a named scaffold, inspect it, then test it on a local or staging site.

Step 1: Choose the classic theme route

If you are extending a classic site or learning its template hierarchy, continue with _s.

Step 2: Generate a named starter

The official WP-CLI command accepts a theme slug and can set the theme name, author, Sass files, or WooCommerce scaffolding for a development WordPress installation.

wp scaffold underscores acme-journal --theme_name="Acme Journal"

The WP-CLI reference lists optional --sassify and --woocommerce flags, which you can add when the theme needs them.

Step 3: Check the generated files and names

Inspect the generated files rather than assuming every scaffold contains the same set. Check the theme header in style.css for its display name and text domain.

Search the directory for the starter prefix before replacing it, then use one slug consistently in translation calls and function names. Keep a copy of the starter files until the edited theme loads.

  • Review style.css for the theme name and other theme metadata.
  • Search the directory for the starter’s text domain and function prefix, then replace them consistently with your own theme slug.
  • Read functions.php and the templates before changing their hooks, template parts, or navigation behavior.
  • Read the bundled readme and language files, and update references that still name _s.

Save this checker as theme_structure_probe.py to test a directory with missing files:

import sys
from pathlib import Path

root = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("probe-theme")
checks = {
    "theme directory": root.is_dir(),
    "theme stylesheet": (root / "style.css").is_file(),
    "block fallback template": (root / "templates" / "index.html").is_file(),
}
for label, passed in checks.items():
    print(f"{label}: {'OK' if passed else 'MISSING'}")
sys.exit(0 if all(checks.values()) else 1)

Run the command on the incomplete-theme directory:

python3 theme_structure_probe.py incomplete-theme

The command output was:

theme directory: OK
theme stylesheet: MISSING
block fallback template: MISSING

The missing stylesheet prevents WordPress from recognizing the theme. The absent fallback also means this directory fails the block-theme structure check.

Terminal output showing missing stylesheet and block fallback files
The checker reports the absent stylesheet and block fallback template.

Use WordPress’s template hierarchy when changing PHP filenames because names affect which requests select each template.

Step 4: Install and verify on a test site

Zip the theme with its files at the archive root, or place it under wp-content/themes. In a test site, install it from Appearance, then Themes, and activate it.

Test the front page, post, page, archive, search, and missing-page views because they may select different templates. Check narrow navigation, keyboard focus, and content without a featured image.

Save this path check as theme_structure_check.py in the parent of probe-theme:

from pathlib import Path

root = Path("probe-theme")
checks = {
    "theme directory": root.is_dir(),
    "theme stylesheet": (root / "style.css").is_file(),
    "block fallback template": (root / "templates" / "index.html").is_file(),
}
for label, passed in checks.items():
    print(f"{label}: {'OK' if passed else 'MISSING'}")

Run the saved file from its parent folder:

python3 theme_structure_check.py

I ran the same command on the sample directory. It printed “theme directory: OK,” “theme stylesheet: OK,” and “block fallback template: OK.” The image shows this output.

Terminal output showing theme directory, stylesheet, and block fallback checks passing
The file check prints three successful structure checks.

This verifies paths only, not PHP or rendering. Review the pages in a browser on the development site.

Step 5: Change presentation without hard-coding assets

Keep design choices in the theme, but place site behavior that should remain after a theme change in a plugin. For example, a custom post type or data-processing hook usually belongs outside a presentation layer. The CodeForGeek guide to building a WordPress plugin covers that separate task.

What to Check Before You Activate the Theme

Use this symptom-and-fix table to check theme structure, identifiers, and asset loading before debugging styling.

SymptomLikely causeCheck or fix
Theme is absent from AppearanceMissing style.css metadata, a nested zip folder, or an incomplete theme directoryCheck the archive root and theme header. For a block theme also check templates/index.html
Block theme check fails on an _s folderClassic and block themes use different required template structuresDo not expect a PHP starter to contain the block theme fallback file. Choose one architecture and test against its handbook
Styles are not loadedHard-coded path, incorrect enqueue hook, or stale browser cacheUse theme URL helpers and wp_enqueue_style(), then inspect the page source and browser network panel
Translations or callbacks use the wrong theme nameStarter text domain or function prefix remains in a fileSearch the whole directory for _s and update references consistently

For Sass, follow the scaffold’s build scripts: browsers need compiled CSS. Remove Sass only after checking that scripts and stylesheet references do not depend on it.

When an asset is missing, inspect the enqueue callback and browser network panel. WordPress recommends enqueue functions rather than hard-coded stylesheet tags, and theme URL helpers tie paths to the active theme.

Check a framework’s release, compatibility, and license before adding it. Enqueue it through WordPress and test phone and desktop layouts.

For a small design, custom CSS may avoid that dependency. If a cached response obscures a correction, compare the requested asset URL and its response before changing the PHP template.

For an activation fatal error, restore a working theme, inspect the PHP error log, then change one item and retest the affected page.

Test representative requests after each template change. The front page and archive can select different files.

A single post or page can use a more specific template. Successful activation means WordPress accepts the theme directory, but it does not confirm that every route, responsive menu, or asset works.

Conclusion

For a fresh block-theme project, follow WordPress’s quick-start guide and check each template type before release.

For further reading, use the official Theme Handbook, the WP-CLI scaffold reference, and CodeForGeek’s article on WordPress publish hooks when you need a hook that belongs in a plugin rather than a theme.

FAQ

These answers separate _s’s original purpose from the choice a new WordPress project has to make.

Is Underscores still maintained?

No. Automattic’s _s repository says the project is inactive, archived for reference, and will not be actively updated. Review its code against your supported WordPress versions before using it.

Can I still generate an Underscores theme with WP-CLI?

The WP-CLI handbook documents wp scaffold underscores and its options. The command scaffolds a classic theme, but that does not mean the _s project is actively maintained.

Should I use Underscores for a new block theme?

No. _s is a classic PHP starter. A block theme needs style.css and templates/index.html and uses block templates with the Site Editor. Follow the WordPress Theme Handbook for that structure.

Pankaj Kumar
Pankaj Kumar

Pankaj Kumar is the founder and CEO of CodeForGeek, with more than 14 years in IT. He is an open-source enthusiast who enjoys sharing what he learns through CodeForGeek and YouTube, with a focus on Python, data analytics, machine learning, Angular, Node.js, and Kafka.

Articles: 337