New to Rust? Grab our free Rust for Beginners eBook Get it free →
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.
| Choose | Theme files and workflow | Good fit |
|---|---|---|
| Underscores | Classic PHP templates, functions.php, CSS and optional JavaScript | Maintaining a classic theme or learning its PHP template flow |
| Block theme | style.css, theme.json, templates/index.html, Site Editor | Starting 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.

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.

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.
| Symptom | Likely cause | Check or fix |
|---|---|---|
| Theme is absent from Appearance | Missing style.css metadata, a nested zip folder, or an incomplete theme directory | Check the archive root and theme header. For a block theme also check templates/index.html |
| Block theme check fails on an _s folder | Classic and block themes use different required template structures | Do not expect a PHP starter to contain the block theme fallback file. Choose one architecture and test against its handbook |
| Styles are not loaded | Hard-coded path, incorrect enqueue hook, or stale browser cache | Use theme URL helpers and wp_enqueue_style(), then inspect the page source and browser network panel |
| Translations or callbacks use the wrong theme name | Starter text domain or function prefix remains in a file | Search 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.




