Skip to main content

Theme switch flow

Switching themes changes how every page on your public site renders — different templates, different CSS, different blocks, different menus, possibly different image variant requirements. The CMS handles most of it automatically, but it's worth understanding what happens so you can recover from edge cases.

What clicking "Activate" does​

In Themes → click a non-active theme card → Activate:

1. Update settings/site.activeThemeId in Firestore
   ↓
2. Subscribe handlers fire — admin re-renders
   ↓
3. Sync theme assets automatically:
   • Upload theme-assets/<new-theme-id>.css
     (with compileCss(savedConfig) baked in if available)
   • Upload theme-assets/<new-theme-id>-menu.js (when present)
   • Upload theme-assets/<new-theme-id>-posts.js (when present)
   ↓
4. Show a toast prompting "Run Regenerate site → All HTML pages
   to render every page with the new theme"

The activate action does NOT regenerate HTML pages automatically. Until you run the regen, your public site still serves the old HTML built with the old theme. Why not auto-regenerate? On a 5 000-post site that's 10+ minutes of waiting that we don't want to lock the admin into.

Recommended post-switch workflow​

1. Switch the theme (via Activate button)
2. Verify the theme assets uploaded — open theme-assets/<id>.css in a browser tab
3. Run Themes → Regenerate site → Everything
4. Spot-check a few pages on the public site
5. Done

Step 3 is the heavy one. Everything runs:

  • All HTML pages (posts + pages + home + category archives)
  • Theme assets (already done by Activate, but cheap to re-run)
  • Sitemaps (the new theme might affect URL discovery)
  • RSS feeds (theme might affect feed rendering — usually doesn't, but Force regenerate is cheap)
  • Search index (some themes opt content out of search)
  • Archives (per-theme archive template might exist)
  • Favicon manifest
  • Any plugin-registered targets

What if the new theme is missing required image variants?​

Each theme declares the image variants it expects (e.g. magazine wants a portrait 800×1200 for hero images). If you switch to a theme that asks for a variant the source images never had, the publisher's pickFormat helper falls through:

  1. Requested format (portrait)
  2. Theme's defaultFormat
  3. Largest available variant
  4. Empty string

So no broken images — the page just uses a smaller / larger / wrongly-cropped variant. To fix:

  • Re-upload affected images via the media library — the new theme's variant set is generated automatically.
  • Or live with the substitute variants (often fine for non-hero usage).

There's no built-in "regenerate all variants for all images" tool. It would require re-running the upload pipeline against every original — but the original is discarded after upload (only variants are kept). For mass re-generation, plan ahead by retaining original sources outside the CMS.

What if the new theme's blocks aren't backward-compatible?​

Themes can register blocks (like magazine's most-read widget or corporate's services-grid). When switching themes:

  • Posts using the OLD theme's blocks still contain <div data-cms-...> markers in their Markdown. The NEW theme's post.html.body filter doesn't recognise these markers, so they pass through as inert <div>s on the published page — visually broken.
  • Posts using core blocks only (paragraphs, headings, images) render fine on every theme.

Recovery options:

  1. Edit each affected post and replace old-theme blocks with new-theme equivalents (or core blocks). Tedious for many posts.
  2. Switch back to the old theme if the breakage is too severe.
  3. Build a small custom plugin that registers the old theme's block transforms in addition to the new theme's — a power-user workaround.

In general: avoid switching themes on sites with heavy use of theme-specific blocks. The default theme uses only core blocks; switching FROM default TO another theme is always safe (except for image variant differences).

What if the old theme had compileCss settings I want to keep?​

settings.themeConfigs[<old-theme-id>] is preserved when you switch away. If you switch from default → magazine → default, your default theme's settings (logo upload, font picks, colour overrides) come back exactly as you left them.

This is intentional — themes can be "swapped" without losing config.

What if the old theme is then uninstalled?​

Uninstalling the old theme removes its bundle from /admin/themes/<id>/ on Flexweg, but settings.themeConfigs.<id> stays in Firestore. Re-installing later would restore the configured behaviour.

Cleanup is manual: edit settings.themeConfigs in Firestore via Firebase Console if you want to delete the orphan config.

What about the old theme's CSS file?​

/theme-assets/<old-theme-id>.css stays on Flexweg after a theme switch. New pages don't reference it (the BaseLayout of the new theme links its own .css), but it's still there occupying space.

The CMS doesn't auto-clean these because:

  • They're harmless (no broken references on the new site)
  • Switching back later is faster if the old CSS is already uploaded

Manual cleanup: Flexweg file manager → delete /theme-assets/<old-theme-id>.css if you want.

Sanity checklist​

After a theme switch, verify:

  • theme-assets/<new-theme-id>.css exists on Flexweg (open the URL directly)
  • The home page renders with the new theme — open /index.html in an incognito window
  • A representative post renders correctly — pick one with images, links, embeds
  • Menus appear correctly (header + footer)
  • The favicon still appears (themes don't manage favicons; flexweg-favicon does)
  • Search trigger still works (theme-specific markup; some themes need [data-cms-search] added)

Continue​