Underscores, often written as _s, is a lean starter theme built for developers who want a clean foundation for custom WordPress theme development. Instead of starting from a blank folder or modifying a bulky prebuilt theme, Underscores gives you the essential templates, functions, and structure needed to build a theme your way.
For beginners, it offers a practical path into how WordPress themes actually work: template hierarchy, theme setup, enqueueing styles and scripts, widget areas, navigation menus, and core theme files. You get enough structure to move forward confidently without being locked into someone else’s design system.
As an Amazon Associate I earn from qualifying purchases.
This guide walks through setting up a local development environment, generating and installing an Underscores theme, understanding its file structure, customizing templates and styles, and preparing a clean custom theme for testing and deployment.
What Underscores Is and Why Developers Use It
Underscores, often written as _s, is a starter theme created for WordPress theme development. It is not meant to be installed as a finished design, sold as-is, or used like a typical mulurpose theme. Instead, it gives developers a clean foundation of template files, WordPress functions, accessibility patterns, and theme structure so they can build a custom theme without starting from an empty folder.
#1 Best Overall
The main value of Underscores is that it provides the essential pieces a WordPress theme needs while staying intentionally minimal. It includes files such as index.php, functions.php, header.php, footer.php, archive templates, single post templates, page templates, and basic styles. These files follow familiar WordPress theme conventions, which makes the project easier to understand, customize, and maintain as it grows.
How Underscores Differs from a Finished Theme
A finished WordPress theme usually includes a complete visual design, layout options, typography choices, color settings, demo content, and sometimes bundled features. Underscores takes the opposite approach. It avoids heavy styling and unnecessary features so developers can make their own decisions about layout, CSS architecture, JavaScript, custom fields, block support, and performance.
- It is lightweight: the codebase is small enough for beginners to inspect file by file.
- It follows WordPress standards: templates, hooks, functions, and escaping patterns are organized in a recognizable way.
- It is design-neutral: you are not fighting against someone else’s CSS or layout system.
- It is practical for learning: it exposes how WordPress themes are assembled instead of hiding everything behind a page builder.
Why Developers Use Underscores
Developers use Underscores because it speeds up the early setup phase while still leaving full control over the final theme. A custom theme needs repetitive groundwork: enqueueing styles and scripts, declaring theme support, loading template parts, handling navigation menus, displaying posts, outputting comments, and organizing reusable functions. Underscores gives you those basics in a form that can be renamed, edited, removed, or expanded to match the project.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →For client work, Underscores is useful because it encourages a clean custom build instead of modifying a bulky commercial theme. That can lead to faster pages, fewer unused settings, simpler maintenance, and a codebase tailored to the actual site requirements. For learning, it gives beginners a realistic view of classic WordPress theme development: the template hierarchy, PHP template tags, content loops, sidebars, menus, and theme setup all appear in context.
Underscores is especially helpful when your goal is to understand and control the theme layer. It does not lock you into a visual framework or a specific design language. You can pair it with plain CSS, Sass, a utility-first workflow, custom JavaScript, Advanced Custom Fields, native blocks, or your own build process. That flexibility is the reason many developers still treat _s as a reliable starting point for building clean, purpose-built WordPress themes.
Setting Up a Local WordPress Development Environment
Before generating an Underscores starter theme, set up WordPress on your own computer so you can build, break, and refine the theme without touching a live site. A local environment gives you a private WordPress installation with PHP, a web server, and a database, closely matching what a real hosting account provides. This is where you will install your starter theme, edit files, test templates, inspect errors, and confirm that changes work before moving anything to production.
For beginners, the simplest route is to use an all-in-one local development app. Tools such as Local, DevKinsta, MAMP, XAMPP, or Laragon can create a WordPress site with minimal configuration. Local and DevKinsta are especially friendly for WordPress projects because they handle server setup, database creation, SSL, and site management through a graphical interface. MAMP, XAMPP, and Laragon are more general-purpose stacks, but they are still widely used and work well once configured.
Recommended Free Tools
Basic local setup checklist
- Install a local server tool: Choose one tool and avoid running multiple stacks at the same time unless you know how to manage port conflicts.
- Create a new WordPress site: Use a project name related to the theme, such as underscores-practice or custom-portfolio-theme.
- Select a modern PHP version: Use a PHP version supported by current WordPress releases, such as PHP 8.1 or newer when available.
- Set up database access: Most tools create the database automatically, but make sure you know how to open phpMyAdmin, Adminer, or the tool’s built-in database viewer.
- Log in to WordPress admin: Confirm that you can reach the dashboard, install themes, activate plugins, and change settings.
Once WordPress is running locally, adjust a few settings to make theme development easier. In the WordPress dashboard, go to Settings and set the site title, tagline, timezone, and permalink structure. For most theme projects, Post name permalinks are a good default because they produce clean URLs and help you test archive, single post, page, and navigation behavior in a realistic way.
You should also turn on debugging in your local WordPress configuration. In the project’s wp-config.php file, enable WP_DEBUG so PHP warnings and theme-related issues are easier to catch during development. Beginners sometimes ignore small warnings because the front end still appears to work, but those warnings often point to missing escaping, undefined variables, incorrect template assumptions, or compatibility problems that should be fixed early.
Recommended development tools
- Code editor: Visual Studio Code, PhpStorm, or another editor with PHP, HTML, CSS, and JavaScript support.
- Browser developer tools: Use Chrome, Firefox, or Edge DevTools to inspect layout, CSS rules, responsive behavior, and console errors.
- Version control: Initialize a Git repository in your theme folder so you can track changes and safely experiment.
- Sample content: Add posts, pages, menus, categories, comments, images, and widgets so your templates are tested with realistic content.
A strong local setup does not need to be complicated, but it should be consistent. Use one local site for the theme, keep the theme files organized under wp-content/themes, and test changes in small steps. With WordPress running locally and your tools ready, you can generate an Underscores theme and install it into an environment designed for safe, practical development.
Generating and Installing an Underscores Starter Theme
Once your local WordPress site is running, the next step is to generate a fresh Underscores starter theme that matches your project. Underscores is not meant to be installed as a finished design. Instead, it gives you a clean foundation with WordPress-ready templates, theme functions, accessibility patterns, and basic structural files that you can rename and build on.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Go to the Underscores generator at underscores.me and enter a theme name that reflects the site or project you are building. For example, if you are creating a theme for a fictional café, you might use Harbor Cafe as the theme name. The generator will automatically create a downloadable ZIP file with your theme folder, PHP templates, stylesheet, JavaScript files, and starter configuration.
Generating the theme files
On the generator page, you will usually provide a few basic details before downloading the theme. The most field is the theme name, because Underscores uses it to create function prefixes, text domains, and file references throughout the theme. Choosing a clear, lowercase-friendly name at the beginning helps avoid unnecessary renaming later.
- Theme Name: The human-readable name shown in the WordPress admin.
- Theme Slug: The folder-friendly version of the name, often lowercase with hyphens.
- Author: Your name, company, or development team.
- Description: A short explanation of what the theme is for.
- Advanced options: Optional fields for namespace, text domain, and Sass support, depending on your workflow.
If you plan to write Sass, enable the Sass option before downloading. This gives you a more organized stylesheet structure with partial files that can be compiled into the final CSS. If you are just starting out, the standard CSS version is perfectly fine and may be easier to follow while learning how WordPress themes are assembled.
Installing the theme in WordPress
After downloading the ZIP file, you can install it through the WordPress dashboard. In your local site, go to Appearance → Themes → Add New → Upload Theme. Choose the ZIP file generated by Underscores, install it, and then activate it. When you visit the front end of your local site, you should see a very plain layout. That plain appearance is expected; Underscores gives you structure rather than a polished visual design.
You can also install the theme manually by unzipping the downloaded file and moving the theme folder into wp-content/themes inside your local WordPress installation. This method is common during development because it lets you open the theme directly in your code editor and track changes with Git. After placing the folder there, return to Appearance → Themes and activate the theme.
Rank #3
First checks after activation
Before editing templates or styles, confirm that the theme loads correctly. Open the home page, a single post, a page, a category archive, and the search results page if your local site has sample content. Check the browser console for missing files or JavaScript errors. In the WordPress admin, confirm that the theme appears with the correct name, author, and description.
- Rename the theme folder only before you begin serious customization.
- Keep the generated text domain consistent across translation functions.
- Activate debugging in your local environment so PHP notices are visible during development.
- Create an initial Git commit immediately after installing the untouched starter theme.
With the starter theme installed and activated, you now have a clean baseline for development. From here, you can begin exploring the file structure, identifying which templates control different parts of the site, and gradually replacing the starter markup and styles with your custom design.
Understanding the Underscores File Structure
After installing and activating your generated Underscores theme, the next step is learning what each file is responsible for. Underscores follows the standard WordPress template hierarchy, so its structure is intentionally familiar to anyone building a custom theme. Instead of giving you a finished design, it provides organized PHP templates, starter styles, JavaScript files, and reusable template parts that you can shape into your own theme.
At the root of the theme folder, you will find several core files that WordPress looks for when loading a theme. The most visible ones are style.css, functions.php, index.php, header.php, footer.php, and sidebar.php. The style.css file contains the theme header comment that identifies the theme in the WordPress admin area, along with starter CSS. The functions.php file is where the theme registers features such as menus, widget areas, editor styles, image sizes, and enqueued scripts or styles.
Core template files
Underscores includes common template files for different WordPress views. These files control how content is displayed depending on the type of request being made. For example, single.php handles individual blog posts, page.php handles standard pages, archive.php handles category, tag, author, and date archives, and search.php handles search results. If WordPress cannot find a more specific template, it eventually falls back to index.php.
- index.php: The fallback template for displaying posts or content lists.
- single.php: Used for individual post views.
- page.php: Used for static pages created in the WordPress admin.
- archive.php: Used for grouped content such as categories, tags, authors, and dates.
- search.php: Used when displaying search result pages.
- 404.php: Used when no matching content is found.
Template parts and reusable markup
One of the most useful parts of the Underscores structure is the template-parts directory. This folder contains smaller reusable files that are included inside larger templates. For example, template-parts/content.php usually controls the default post preview or post content layout, while template-parts/content-page.php is used for pages. This keeps your templates cleaner because repeated markup does not need to be copied across mulle files.
You will also see an inc directory, which stores supporting PHP files. Common files include custom-header.php, template-tags.php, and template-functions.php. The template-tags.php file is often used for small helper functions that output post metadata, navigation, or other repeated elements. The template-functions.php file is a good place for functions that adjust theme behavior without crowding the main functions.php file.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchAssets, scripts, and styles
Underscores also includes directories for front-end assets. The js folder contains starter JavaScript files, such as navigation behavior for responsive menus. The sass folder may be included if you selected the Sass option when generating the theme. If you are using Sass, you will edit the partial files in that folder and compile them into the main stylesheet. If you are not using Sass, you can work directly in style.css or create additional CSS files and enqueue them properly in functions.php.
A good workflow is to treat the file structure as a map rather than editing everything in one place. Change layout markup in templates, reusable content blocks in template-parts, theme setup and asset loading in functions.php, helper functions in inc, and visual presentation in your stylesheets. Keeping these responsibilities separate makes the theme easier to debug, expand, and hand off to another developer later.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Customizing Templates, Styles, and Theme Functions
Once the Underscores theme is installed and its file structure feels familiar, the real work begins: turning the starter theme into a design that matches your project. The safest approach is to customize in small, focused steps. Start with the main templates, then move into reusable template parts, then refine styles and theme functions. This keeps the theme easy to test and prevents large changes from becoming difficult to debug.
Editing templates and template parts
Underscores follows the standard WordPress template hierarchy, so files such as index.php, single.php, page.php, archive.php, and search.php control different types of views. For example, single.php handles individual blog posts, while page.php handles static pages. Shared layout pieces live in files such as header.php, footer.php, and sidebar.php, while smaller content sections are usually stored in the template-parts directory.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →A practical first customization is to adjust the markup in template-parts/content.php, which is commonly used for post listings. You might add a wrapper for a card layout, move the featured image above the title, or change how excerpts are displayed. For single posts, template-parts/content-single.php is a good place to refine author details, post meta, categories, tags, and navigation between posts. Keep reusable patterns in template parts instead of duplicating the same markup across mulle template files.
Organizing styles
Underscores includes a main style.css file with the required theme header at the top. You can write CSS directly in this file for smaller projects, but larger themes benefit from a more organized workflow. Many developers split styles into partials using Sass, then compile them into the final stylesheet loaded by WordPress. Common sections include base typography, layout, navigation, forms, buttons, comments, widgets, and responsive rules.
- Start with global styles: set body typography, link colors, headings, spacing, and image behavior.
- Define layout rules: create containers, content widths, grids, and sidebar behavior.
- Style components: handle menus, post cards, pagination, buttons, forms, and comment areas.
- Add responsive adjustments: test navigation, columns, images, and spacing across common screen sizes.
Working in functions.php
The functions.php file is where you add theme features and enqueue assets. Underscores already includes a setup function that registers support for common WordPress features such as title tags, post thumbnails, HTML5 markup, custom backgrounds, and menus. You can extend this setup by adding image sizes, registering additional menu locations, or enabling editor styles so the block editor more closely matches the front end.
Use wp_enqueue_style() and wp_enqueue_script() to load CSS and JavaScript instead of hardcoding assets in template files. This allows WordPress to manage dependencies, versions, and loading order correctly. For example, your main stylesheet should be enqueued from functions.php, and custom scripts should be loaded with dependencies declared when needed. If a script only supports a specific template, conditionally enqueue it to avoid unnecessary front-end weight.
Free tools Windows power users keep installed
One-click scans. No signup required.
As you customize, keep theme-specific presentation in the theme and plugin-style features out of it. A custom post type, analytics integration, or major functionality that should remain after a theme switch usually belongs in a plugin. This separation helps your Underscores-based theme stay clean, portable, and focused on layout, templates, and visual presentation.
Preparing Your Theme for Testing and Deployment
Before moving your Underscores-based theme from your local environment to a staging or live WordPress site, give it a full review. A starter theme can become production-ready only after its templates, styles, scripts, accessibility features, and WordPress integrations have been tested together. This step helps catch broken layouts, missing template parts, untranslated strings, PHP warnings, and asset-loading issues before visitors or clients see the site.
Run through a practical testing checklist
Start by testing the theme with real WordPress content rather than only a few sample posts. Add posts with featured images, categories, tags, galleries, quotes, long titles, nested comments, empty search results, and password-protected content. Check pages, archives, single posts, search results, the 404 page, menus, widgets, and any custom template files you created. Resize the browser and test on mobile, tablet, and desktop widths to make sure your responsive styles behave as expected.
- Enable debugging: In your local or staging
wp-config.php, turn on WordPress debugging and check for PHP notices, deprecated functions, and template errors. - Validate markup: Inspect the generated HTML for missing closing tags, duplicated IDs, and incorrect heading order.
- Check accessibility: Confirm that menus can be used with a keyboard, images have useful alt text where needed, form fields have labels, and color contrast is readable.
- Review browser support: Test current versions of Chrome, Firefox, Safari, and Edge, especially if your CSS uses newer layout features.
- Test plugins carefully: Install common plugins the site will use, such as SEO, forms, ecommerce, caching, or custom fields plugins, and check that your theme does not conflict with their output.
Clean up development files and theme metadata
Next, prepare the theme folder itself. Update the header comment in style.css with the final theme name, author, version, license, text domain, and description. Make sure the screenshot file is named screenshot.png and represents the finished design. Remove unused images, test templates, temporary CSS, console logs, commented-out experiments, and any local-only configuration. If you used Sass, PostCSS, or a bundler, compile the final assets and avoid uploading unnecessary source maps or dependency folders unless your deployment process requires them.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errors| Area | What to verify |
|---|---|
| Templates | All page types load correctly without PHP warnings or missing template parts. |
| Assets | CSS and JavaScript are enqueued through WordPress and load only where needed. |
| Text | User-facing strings are translation-ready and use the correct text domain. |
| Performance | Images are optimized, unused styles are removed, and render-blocking assets are limited. |
When the theme is ready, deploy it first to a staging site that mirrors the live server as closely as possible. Upload the theme through the WordPress admin area, SFTP, Git-based deployment, or your host’s deployment tools. After activation, revisit the testing checklist with production-like content and server settings. Once everything is stable, back up the live site, deploy during a low-traffic window, activate the theme, flush caches, regenerate any critical CSS if your caching plugin uses it, and perform a final front-end review. A careful release process keeps your custom Underscores theme clean, maintainable, and easier to improve over time.
Frequently Asked Questions
Is Underscores still a good starter theme for modern WordPress development?
Yes, Underscores is still useful if you want to build a classic custom WordPress theme from a clean, minimal foundation. It gives you standard template files, theme functions, accessibility basics, and WordPress conventions without forcing a design system or page builder workflow.
Do I need to know PHP before using Underscores?
You should know basic PHP syntax and how WordPress template tags work, but you do not need to be an advanced PHP developer to start. Most beginner customizations involve editing template files, adding theme support in functions.php, enqueueing styles and scripts, and adjusting loops or partials.
Should I edit the Underscores theme directly or create a child theme?
With Underscores, you normally edit the generated theme directly because it is intended to become your custom theme. Child themes are more useful when you are modifying a parent theme that will receive updates, while an Underscores-based theme is your own codebase from the start.
What files should I customize first in an Underscores theme?
Start with style.css for theme metadata and global styles, functions.php for theme setup and asset loading, and template parts inside the template-parts folder for post and page markup. After that, adjust header.php, footer.php, index.php, single.php, page.php, and archive.php based on the layouts your site needs.
How do I prepare an Underscores-based theme for launch?
Test the theme with real posts, pages, menus, widgets, featured images, comments, and different screen sizes before deployment. You should also enable WP_DEBUG during development, check accessibility basics, validate that scripts and styles are enqueued correctly, and remove unused starter code or placeholder styles before packaging the theme.
Bottom Line
Underscores gives you a clean, practical starting point for learning WordPress theme development without locking you into a bulky framework. By understanding its file structure, setting up a sensible workflow, and customizing templates, styles, and functions carefully, you can build a theme that is lightweight, maintainable, and truly your own.
Your next step is to download _s, create a local development environment, and start making small changes one file at a time. Treat the starter theme as a learning tool as much as a foundation, and you’ll quickly gain the confidence to build cleaner custom WordPress themes from scratch.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
