Child Theme Setup (overview)

warning

Do this on staging first. Theme activation and PHP changes affect the whole site and can cause downtime if misconfigured.

Prerequisites

File	Required	Purpose	Path
style.css	Yes	Declares the child theme and sets the Template: (parent)	/wp-content/themes/generatepress-child/style.css
functions.php	Yes	Adds hooks/filters and enqueues assets	/wp-content/themes/generatepress-child/functions.php
screenshot.png	Optional	Dashboard thumbnail	/wp-content/themes/generatepress-child/screenshot.png

Safety Notes

• Update safety: your changes live outside the parent theme.
• Auditability: you can put the child theme under Git and deploy it like application code.
• Control: hooks/filters let you customize without forking templates.

How It Works

WordPress loads the parent theme, then the child theme. The child theme can enqueue its own assets and attach callbacks to hooks. For templates, WordPress checks the child theme first and falls back to the parent.

Step-by-Step Setup

Step 1: Create the Child Theme Directory

create-child-theme-folders.sh

cd /var/www/html
mkdir -p wp-content/themes/generatepress-child

Step 2: Create style.css with a Valid Header

create-style-css.sh

cat > wp-content/themes/generatepress-child/style.css <<'EOF'
/*
Theme Name: GeneratePress Child
Template: generatepress
Version: 0.1.0
*/
EOF

Step 3: Create functions.php and Enqueue Styles

create-functions-php.sh

cat > wp-content/themes/generatepress-child/functions.php <<'EOF'
<?php

add_action( 'wp_enqueue_scripts', function() {
    wp_enqueue_style(
        'generatepress-parent',
        get_template_directory_uri() . '/style.css'
    );

    wp_enqueue_style(
        'generatepress-child',
        get_stylesheet_directory_uri() . '/style.css',
        array( 'generatepress-parent' ),
        filemtime( get_stylesheet_directory() . '/style.css' )
    );
} );
EOF

caution

If you use cat > file on a server, ensure you are writing to the correct docroot. A wrong path can create files outside WordPress and waste debugging time.

Step 4: Activate the Child Theme

activate-child-theme.sh

cd /var/www/html
wp theme activate generatepress-child
wp theme list

Expected output (example):

Success: Switched to 'GeneratePress Child' theme.

Step 5: Verify Parent/Child Relationship

verify-template-header.sh

cd /var/www/html
grep -n "^Template:" wp-content/themes/generatepress-child/style.css

Expected output:

Template: generatepress

Optional Configuration

Example: Add a Small Notice (Prove Hooks Work)

wp-content/themes/generatepress-child/functions.php

<?php

add_action( 'generate_before_header', function() {
    echo '<div class="gp-child-proof">Child theme active</div>';
} );

Best Practices

Practice	Why
Keep child theme minimal at first	Smaller surface area for failures
Put non-trivial code in /inc/ inside the child theme	Cleaner organization and easier testing
Commit early to Git	Enables rollback when a change breaks rendering
Use filemtime() for cache-busting in staging	Prevents stale CSS while iterating

Troubleshooting

Problem	Cause	Fix
Theme not visible in admin	Missing header in style.css	Ensure Theme Name: and Template: exist
Child theme activates but looks unstyled	Parent styles not enqueued	Verify the parent enqueue in functions.php
Activation fails	Wrong directory name	Confirm directory is generatepress-child and run wp theme list
Fatal error on load	PHP syntax error	Check /usr/local/lsws/logs/error.log and fix functions.php

Hands-On

1. Create the child theme on staging and activate it.
2. Add a single action to print a message above the header.
3. Remove the action and confirm the site returns to baseline.

Quick Reference

Task	Command
Create child theme folder	mkdir -p wp-content/themes/generatepress-child
Activate child theme	wp theme activate generatepress-child
Verify active stylesheet	wp option get stylesheet

What's Next

• Next module: Customization Fundamentals
• Next lesson: Customizer Essentials