Remote-Theme Consumer Checklist

What you’ll do: wire up the files and config that GitHub Pages does not inherit when you consume Zer0-Mistakes via remote_theme, so search, navigation, comments, and internal links all work.

Why this is needed

remote_theme only delivers _layouts/, _includes/, _sass/, and assets/. It does not deliver _config.yml, _data/, _plugins/, or any root / pages/ files. GitHub Pages additionally runs Jekyll in safe: true mode, which ignores _plugins/*.rb — so every custom generator in this theme (search, sitemap, author pages, content statistics, preview images) never runs on a Pages build of a consumer site.

The result is a chain of silent degradations. The checklist below is the shortest path through all of them.

Prerequisites

• A GitHub repository with Pages enabled
• remote_theme: "bamr87/zer0-mistakes" in your _config.yml

The checklist

1. Add jekyll-include-cache to your plugins:

_layouts/root.html uses {% include_cached %}. Without the plugin, the first build dies on Unknown tag 'include_cached'.

# _config.yml
plugins:
  - jekyll-include-cache

2. Re-declare structure in your _config.yml

None of these are inherited from the theme — declare your own: collections, defaults, permalink, theme_skin, theme_color, theme_background.

3. ⚠️ Do not copy the theme’s _config.yml wholesale

The theme’s config ships a live google_analytics: ID and a PostHog api_key:. Copying them sends your visitors’ analytics to the theme author. Strip or replace the analytics and identity blocks, and leave posthog / ai_chat off unless you own the project and deploy the proxy.

4. Commit your own _data/

At minimum:

• _data/navigation/main.yml — without it the navbar is empty.
• _data/ui-text.yml — read as site.data.ui by the footer, breadcrumbs, and search modal; without it labels are blank.
• _data/authors.yml — without it bylines and author cards have no data.

5. Hand-author /search.json and /sitemap/

Both endpoints are produced by _plugins/search_and_sitemap_generator.rb, which Pages skips in safe mode — and the committed fallback stubs are not delivered by remote_theme. So the navbar search returns nothing and /sitemap/ 404s.

The search layout and _includes/search-data.json are delivered, so add a single file in your repo root:

# /search.json
---
layout: search
permalink: /search.json
sitemap: false
---

Add a /sitemap/ page too (or rely on the jekyll-sitemap plugin’s /sitemap.xml — the footer falls back to it automatically when no /sitemap/ page exists).

6. Author profile pages 404 unless you commit them

_plugins/author_pages_generator.rb is plugin-only on Pages. The theme chrome no longer links to author profiles that don’t exist in your build, so empty bylines degrade gracefully — but if you want /authors/:key/ pages, commit them yourself.

7. Statistics pages render empty

_plugins/content_statistics_generator.rb is plugin-only and the data file isn’t delivered. Don’t rely on the stats dashboard on a pure remote-theme Pages build.

8. Don’t add jekyll-mermaid

It isn’t on the GitHub Pages plugin whitelist. The theme renders Mermaid client-side from a vendored bundle already — adding the plugin just breaks the build.

9. Turn ai_chat and posthog off

Both ship enabled in the theme config. Leave them off unless you deploy the chat proxy / own the analytics project. See item 3.

10. Use the correctly-spelled giscus: key

Comments read site.giscus (and site.giscus.enabled). Define your block under giscus: — a misspelling silently disables comments with no error.

# _config.yml
giscus:
  enabled: true
  data-repo-id: "..."
  data-category-id: "..."

Configuring theme chrome links

The theme chrome links to a few section pages it assumes exist. When your site puts them elsewhere (or doesn’t have them), point the theme at the right base or turn the feature off — so nothing 404s:

Tag badges, the local-graph “Full graph” link, the breadcrumb collection-root crumb, and author byline links are all existence-gated: when the target page isn’t in your build they render as plain text instead of broken links.

Verify

• Open the navbar search and type — results appear (item 5).
• The navbar and footer show your labels and links (items 2, 4).
• View source on a post — no google_analytics ID or PostHog key you didn’t set (item 3).
• Run a link checker over the built _site — no theme-injected 404s.

See also

• Deploy to GitHub Pages
• Custom Domain