Why Use a Child Theme
warning
Editing functions.php can break the entire site if you introduce a PHP error. Make changes on staging first and keep rollback access (SSH + WP-CLI).
What a Child Theme Is (and What It Is Not)
| Term | Meaning | Where it lives |
|---|---|---|
| Parent theme | Vendor theme you update (GeneratePress) | /wp-content/themes/generatepress/ |
| Child theme | Your customization layer (update-safe) | /wp-content/themes/generatepress-child/ |
| Inheritance | WP loads child templates first, then parent | Template hierarchy behavior |
| Hooks/filters | Primary customization mechanism | add_action() / add_filter() in child theme |
Key Concepts
- Update safety: parent theme updates overwrite modified parent files.
- Team workflow: a child theme can be a Git repo with reviewable changes.
- Portability: you can move the child theme between environments (local/staging/prod).
- Scope control: you keep your custom code and assets isolated from vendor code.
How It Works
When a child theme is active, WordPress loads the parent theme first, then loads the child theme. For templates, WP checks the child theme directory first. For behavior changes, you add hooks/filters in the child theme.
flowchart TD
WP[WordPress] --> PARENT[Parent: generatepress]
PARENT --> CHILD[Child: generatepress-child]
CHILD --> CB[Child hooks/filters]
CHILD --> CT["Child templates (optional)"]
CT -->|fallback| PT[Parent templates]
Best Practices
| Practice | Why |
|---|---|
| Keep the child theme small | Smaller blast radius, easier audits |
| Prefer hooks/filters over copying templates | Less merge debt on updates |
| Use Git for the child theme | Rollback and change history |
| Add a README with deploy notes | Helps future maintainers |
| Escape output and sanitize inputs | Security and stability |
Version your theme in style.css | Makes deployments and rollbacks traceable |
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Child theme not selectable | Missing Theme Name: header | Fix style.css header and re-scan themes |
| Child theme activates but styling is missing | Parent style not enqueued | Enqueue parent style in child functions.php |
| White screen after edit | PHP syntax error | Check /usr/local/lsws/logs/error.log and fix functions.php |
| Template override not applied | Wrong file path/name | Verify the parent template name and mirror the path exactly |
Self-Check
- Explain why editing the parent theme is risky.
- Describe three things you would put in a child theme (and one thing you would not).
- Outline a safe workflow: staging changes, small commits, and a rollback plan.
Quick Reference
| If you need to... | Prefer... |
|---|---|
| Add versioned CSS/JS and small hooks | A child theme |
| Add site features (APIs, schema, CPTs) | A site plugin or MU-plugin |
| Change markup in one spot | Hooks/Elements before template overrides |
What's Next
- Next: Child Theme Structure
- Related: Child Theme Setup (overview)