Customizer Essentials

warning

Customizer changes can affect the entire site. On production, make large changes on staging first and plan a cache purge (LSCache) after deployment.

Customizer Essentials Explained

Concept	What it is	Where to look
Panels/sections	The UI grouping inside Appearance -> Customize	WordPress Customizer UI
Settings/controls	Individual knobs (width, colors, fonts)	/wp-content/themes/generatepress/inc/customizer/
Theme mods	Saved values for the active theme	wp option get theme_mods_generatepress
Defaults	Fallback values when no theme mod exists	Theme defaults + filters
Export/import	Move settings between staging and production	wp customizer export / wp customizer import (if available)

Why It Matters

• Reduces custom CSS and one-off fixes.
• Makes design decisions reproducible (export/import, diffs).
• Helps debugging: you can prove whether a layout issue is a setting, a hook, or a template override.

How It Works

GeneratePress registers Customizer options via modular PHP config files. When you save changes, WordPress stores the values as theme mods. On the front end, the theme reads those mods and outputs CSS/markup.

flowchart LR
  UI[Customizer UI] --> SAVE[Save]
  SAVE --> MODS[(theme_mods_generatepress)]
  MODS --> GP[GeneratePress output]
  GP --> HTML[HTML/CSS]

Practical Walkthrough

Step 1: Inspect the GeneratePress Customizer Files

inspect-gp-customizer-files.sh

cd /var/www/html/wp-content/themes/generatepress
ls inc/customizer
ls inc/customizer/configs | head -n 30

Expected output (example):

controls.php  defaults.php  init.php  configs/
layout.php
colors.php
typography.php

Step 2: View Saved Theme Mods

view-theme-mods.sh

cd /var/www/html
wp option get theme_mods_generatepress --format=json > /tmp/theme_mods_generatepress.json
wc -l /tmp/theme_mods_generatepress.json

Step 3: Locate the Source of a Specific Setting

Example: find where layout settings are declared.

locate-layout-settings.sh

cd /var/www/html/wp-content/themes/generatepress
grep -R "layout" -n inc/customizer/configs | head -n 40

Step 4: Check If Customizer Export/Import Is Available

check-wp-cli-customizer-command.sh

cd /var/www/html
wp help customizer 2>/dev/null || echo "No wp customizer command found"

Practical Examples

Example 1: Diff Settings Between Two Snapshots

diff-theme-mods-snapshots.sh

cd /var/www/html
wp option get theme_mods_generatepress --format=json > /tmp/theme_mods_generatepress.A.json

# Make a small change in the Customizer, save, then run:
wp option get theme_mods_generatepress --format=json > /tmp/theme_mods_generatepress.B.json

diff -u /tmp/theme_mods_generatepress.A.json /tmp/theme_mods_generatepress.B.json | head -n 80

Outcome: you can explain exactly what changed without guessing.

Example 2: Export/Import Workflow (If Available)

export-import-customizer.sh

cd /var/www/html
wp customizer export > gp-customizer.json
wp customizer import gp-customizer.json

caution

Run imports on staging first. A broken import can change layout and typography site-wide.

Best Practices

Practice	Why
Make large design changes on staging	Protects production uptime
Keep a baseline export (gp-customizer.json)	Enables repeatable deploys
Prefer global settings over page-level hacks	Prevents inconsistent design
Purge caches after major changes	LSCache can serve stale HTML/CSS

Troubleshooting

Issue	Cause	Fix
Changes not visible	Caching	Purge LSCache and test logged-out
Customizer preview broken	Plugin JS conflict	Disable plugins on staging and re-test
Settings missing	Theme/plugin mismatch	Verify generatepress + gp-premium versions
Theme mods look empty	Stored under different key	List options: `wp option list

Hands-On

1. Export the current theme mods to /tmp/theme_mods_generatepress.json.
2. Change one layout setting in the Customizer and diff before/after.
3. Write a short change log entry (what changed, why, and rollback).

Quick Reference

Task	Command
List Customizer configs	ls /var/www/html/wp-content/themes/generatepress/inc/customizer/configs
Dump theme mods	wp option get theme_mods_generatepress --format=json
Search a setting	grep -R "setting" -n /var/www/html/wp-content/themes/generatepress/inc/customizer

What's Next

• Next: Global Design Variables
• Related: Customizer-Based Design System