Multisite & Reusability

warning

Reusability only works if you keep site-specific data out of the theme. Avoid hard-coded domains, API keys, and content assumptions.

Multisite & Reusability Explained

Reuse target	What changes	What stays the same
Multiple single sites	branding + content	theme structure + patterns
Multisite network	per-site tokens	base child theme code
Agency starter	client-specific modules	shared hooks/CSS utilities

Why It Matters

• Agencies and teams save time by reusing a stable base.
• A reusable base theme reduces bugs and makes audits easier.
• Multisite demands consistency, but allows per-site variation.

How It Works

You build a base child theme with:

• stable structure (inc/, assets/)
• tokens (CSS variables)
• safe hooks/filters

Then you layer site-specific configuration via:

• Customizer exports
• small CSS token overrides
• environment configuration (server-managed)

Practical Walkthrough

Step 1: Create a Base Theme Folder (Starter)

create-base-child-theme.sh

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

Step 2: Package the Theme as a Deployable Artifact

package-base-theme.sh

cd /var/www/html
tar -czf /tmp/gp-child-base.tgz -C wp-content/themes gp-child-base
ls -lh /tmp/gp-child-base.tgz

Step 3: Multisite Theme Enable (Optional)

On multisite, themes must be enabled network-wide before sites can use them.

multisite-enable-theme.sh

cd /var/www/html
wp core is-installed
wp theme list | head -n 20

Step 4: Define What Is Site-Specific

Write down what changes per site:

• token overrides (colors)
• Customizer export/import
• element display rules

Practical Examples

Example 1: Separate Tokens Per Site

Base theme provides tokens.css:

assets/css/tokens.css

:root {
  --brand-primary: #1e3a8a;
  --brand-surface: #f8fafc;
}

Each site overrides only the variables (not the full layout system).

Example 2: Use Customizer Exports as Site Profiles

Store gp-customizer.json per site and import it after provisioning.

Example 3: Keep a Component Library

Reuse:

• patterns
• elements
• utility CSS

Avoid copying full pages.

Example 4: Per-Site Token Overrides

Keep the base theme stable and override only CSS variables per site (small file, easy to diff).

Best Practices

Practice	Why
Base theme + thin site overrides	Prevents forks
No secrets in the theme	Security
Document expected plugins	Prevents missing dependencies
Version your base theme	Safe rollouts
Keep overrides small	Reuse works best with thin deltas

Troubleshooting

Symptom	Cause	Fix
Theme works on one site but not another	Hidden dependencies	Document required plugins and settings
Tokens not applied	CSS not enqueued	Verify enqueue and cache busting
Multisite cannot activate theme	Theme not enabled	Enable in network admin / WP-CLI workflow

Hands-On

1. Create a base child theme folder.
2. Add inc/ and assets/ structure.
3. Package it to /tmp/gp-child-base.tgz.
4. Write a README section: "What changes per site".
5. Create one token override file for a second site and document it.

Quick Reference

reuse-cheatsheet.sh

cd /var/www/html
tar -tzf /tmp/gp-child-base.tgz 2>/dev/null | head

What's Next

• Next: Versioning & Deployment
• Related: Export & Backup