WordPress Starter Theme Guide: Build Custom Sites From Scratch

your-theme/
├── style.css              ← Theme metadata + base styles (REQUIRED)
├── index.php              ← Ultimate fallback template (REQUIRED)
├── functions.php          ← Theme setup, enqueue, menus, sidebars
├── screenshot.png         ← Theme thumbnail (1200×900px recommended)
│
├── header.php             ← <head> + opening <body> + site header
├── footer.php             ← Site footer + closing </body>
├── sidebar.php            ← Widget area template
│
├── single.php             ← Individual blog post
├── page.php               ← Static page
├── archive.php            ← Post listings (category, tag, date, author)
├── search.php             ← Search results
├── 404.php                ← Not found page
├── front-page.php         ← Homepage (if set to static page)
├── home.php               ← Blog posts page
│
├── template-parts/        ← Reusable template components
│   ├── content.php        ← Post content in The Loop
│   ├── content-single.php ← Single post content
│   ├── content-page.php   ← Page content
│   └── content-none.php   ← No results found
│
├── inc/                   ← PHP includes (modular functions)
│   ├── customizer.php     ← Theme Customizer settings
│   ├── template-tags.php  ← Custom template functions
│   └── template-functions.php
│
├── assets/                ← Static assets
│   ├── css/
│   │   └── main.css       ← Compiled/custom styles
│   ├── js/
│   │   └── main.js        ← Theme JavaScript
│   ├── images/
│   └── fonts/
│
├── languages/             ← Translation files
│   └── theme-slug.pot
│
└── theme.json             ← Block editor settings (optional for classic)

Quick start with Underscores (_s)

# 1. Install LocalWP and create a new WordPress site
# 2. Navigate to your themes directory
cd ~/Local Sites/my-site/app/public/wp-content/themes/

# 3. Option A: Generate from underscores.me (download + unzip)
# Visit https://underscores.me → enter theme name → download

# 4. Option B: Clone from GitHub
git clone https://github.com/Automattic/_s.git my-theme
cd my-theme

# 5. Search-replace '_s' with your theme slug
# Replace '_s' with 'my_theme' in all files (functions, text domain, etc.)

# 6. Activate in WP Admin → Appearance → Themes

functions.php, Complete starter configuration

<?php
/**
 * Theme functions and definitions.
 */

// === THEME SETUP ===
function mytheme_setup() {
    // Add title tag support
    add_theme_support('title-tag');

    // Featured images
    add_theme_support('post-thumbnails');
    set_post_thumbnail_size(1200, 630, true);
    add_image_size('hero', 1920, 800, true);
    add_image_size('card', 600, 400, true);

    // Custom logo
    add_theme_support('custom-logo', array(
        'height'      => 100,
        'width'       => 400,
        'flex-height' => true,
        'flex-width'  => true,
    ));

    // HTML5 markup
    add_theme_support('html5', array(
        'search-form', 'comment-form', 'comment-list',
        'gallery', 'caption', 'style', 'script',
    ));

    // Block editor support
    add_theme_support('wp-block-styles');
    add_theme_support('align-wide');
    add_theme_support('editor-styles');
    add_editor_style('assets/css/editor-style.css');
    add_theme_support('responsive-embeds');

    // Register navigation menus
    register_nav_menus(array(
        'primary' => __('Primary Menu', 'my-theme'),
        'footer'  => __('Footer Menu', 'my-theme'),
    ));
}
add_action('after_setup_theme', 'mytheme_setup');

// === ENQUEUE STYLES & SCRIPTS ===
function mytheme_scripts() {
    // Main stylesheet
    wp_enqueue_style(
        'mytheme-style',
        get_template_directory_uri() . '/assets/css/main.css',
        array(),
        filemtime(get_template_directory() . '/assets/css/main.css')
    );

    // Theme JavaScript (in footer)
    wp_enqueue_script(
        'mytheme-script',
        get_template_directory_uri() . '/assets/js/main.js',
        array(),
        filemtime(get_template_directory() . '/assets/js/main.js'),
        true  // Load in footer
    );

    // Comment reply script (only when needed)
    if (is_singular() && comments_open()) {
        wp_enqueue_script('comment-reply');
    }
}
add_action('wp_enqueue_scripts', 'mytheme_scripts');

// === REGISTER SIDEBARS / WIDGET AREAS ===
function mytheme_widgets_init() {
    register_sidebar(array(
        'name'          => __('Sidebar', 'my-theme'),
        'id'            => 'sidebar-1',
        'before_widget' => '<section class="widget %2$s">',
        'after_widget'  => '</section>',
        'before_title'  => '<h3 class="widget-title">',
        'after_title'   => '</h3>',
    ));
    register_sidebar(array(
        'name'          => __('Footer Widgets', 'my-theme'),
        'id'            => 'footer-1',
        'before_widget' => '<div class="footer-widget %2$s">',
        'after_widget'  => '</div>',
        'before_title'  => '<h4 class="widget-title">',
        'after_title'   => '</h4>',
    ));
}
add_action('widgets_init', 'mytheme_widgets_init');

// === PERFORMANCE: Remove unnecessary features ===
// Remove emoji scripts
remove_action('wp_head', 'print_emoji_detection_script', 7);
remove_action('wp_print_styles', 'print_emoji_styles');

// Remove oEmbed discovery
remove_action('wp_head', 'wp_oembed_add_discovery_links');

// Disable XML-RPC (security + performance)
add_filter('xmlrpc_enabled', '__return_false');

inc/customizer.php, Register custom settings

<?php
function mytheme_customize_register($wp_customize) {

    // === HERO SECTION ===
    $wp_customize->add_section('mytheme_hero', array(
        'title'    => __('Hero Section', 'my-theme'),
        'priority' => 30,
    ));

    // Hero heading
    $wp_customize->add_setting('hero_heading', array(
        'default'           => 'Welcome to Our Site',
        'sanitize_callback' => 'sanitize_text_field',
        'transport'         => 'postMessage', // Live preview
    ));
    $wp_customize->add_control('hero_heading', array(
        'label'   => __('Hero Heading', 'my-theme'),
        'section' => 'mytheme_hero',
        'type'    => 'text',
    ));

    // Hero CTA button text
    $wp_customize->add_setting('hero_cta_text', array(
        'default'           => 'Get Started',
        'sanitize_callback' => 'sanitize_text_field',
    ));
    $wp_customize->add_control('hero_cta_text', array(
        'label'   => __('CTA Button Text', 'my-theme'),
        'section' => 'mytheme_hero',
        'type'    => 'text',
    ));

    // Primary color
    $wp_customize->add_setting('primary_color', array(
        'default'           => '#2563eb',
        'sanitize_callback' => 'sanitize_hex_color',
        'transport'         => 'postMessage',
    ));
    $wp_customize->add_control(new WP_Customize_Color_Control(
        $wp_customize, 'primary_color', array(
            'label'   => __('Primary Color', 'my-theme'),
            'section' => 'colors',
        )
    ));
}
add_action('customize_register', 'mytheme_customize_register');

// Output custom CSS from Customizer settings
function mytheme_customizer_css() {
    $primary = get_theme_mod('primary_color', '#2563eb');
    ?>
    <style>
        :root { --color-primary: <?php echo esc_attr($primary); ?>; }
    </style>
    <?php
}
add_action('wp_head', 'mytheme_customizer_css');