A remote_theme is a roommate who moves out and takes the furniture, leaves the curtains, and swears everything is “basically still there.” It is, technically. The layouts came. The styles came. The thing that fills in the navbar did not come.
remote_theme delivers the outfit: _layouts, _includes, _sass, assets. It does not deliver the suitcase: your _config.yml, your _data, and a couple of stub pages that turn out to be load-bearing. Here is the packing list, in the order you’ll discover each one is missing.
1. The include-cache plugin (or the build just dies)
Symptom: Your build fails with Liquid Exception: Unknown tag 'include_cached'. No site. Just a red X and a quiet feeling.
Cause: The theme’s includes call include_cached, a tag that ships with the jekyll-include-cache plugin — and you don’t have it.
Fix: Add it to your plugins list. It’s on the GitHub Pages allowlist, so it actually runs.
# _config.yml
plugins:
- jekyll-include-cache
2. The theme’s _config.yml is not inherited
Symptom: Permalinks are wrong, collections don’t exist, the skin is whatever the default is. You configured nothing, so nothing is configured.
Cause: remote_theme ships code, not configuration. The theme author’s _config.yml stays on the theme’s repo. You re-declare collections, defaults, permalink, theme_skin, all of it, yourself.
Fix: Copy the settings you need into your own _config.yml. But — and this is the part that should make you sit up — do not copy it wholesale.
The theme’s _config.yml contains the theme author’s real analytics identity: a live google_analytics ID and a PostHog api_key. Copy those and every visitor to your site quietly phones home to someone else’s dashboard. You’d be doing unpaid data collection for a stranger.
# Strip these. Replace with your own or delete them.
google_analytics: "" # not the theme author's G-XXXXXXX
posthog:
api_key: "" # not the theme author's key
When this goes wrong, it goes wrong invisibly — the site works fine, and someone else’s funnel just got more “engaged users.”
3. _data/ does not come with you
Symptom: Empty navbar. Footer with blank labels. Landing page with no cards. A sidebar that gestures at content that isn’t there.
Cause: The theme’s _data files live on the theme repo. They are not delivered. Your includes look for site.data.navigation, find nothing, and render nothing very politely.
Fix: Commit your own _data/. At minimum:
_data/
navigation/main.yml # navbar links
ui-text.yml # button + label strings
authors.yml # who wrote what
4. /search.json and /sitemap/ return 404
Symptom: Search does nothing. Your sitemap is a 404. Search engines shrug.
Cause: Those files are produced by a Ruby generator plugin. GitHub Pages runs Jekyll in --safe mode and ignores plugins that aren’t on its allowlist. The committed stubs that would trigger generation live on the theme repo, and remote_theme doesn’t deliver content pages — only layouts/includes/sass/assets. So nothing generates and nothing was delivered. Double miss.
Fix: Hand-create them as ordinary pages.
# search.json
---
layout: search
---
<!-- sitemap/index.md -->
---
title: Sitemap
permalink: /sitemap/
---
5. Author pages (/authors/:key/) 404
Symptom: You link to an author, the byline is proud, the link is a cliff.
Cause: Same story — those per-author pages are minted by a plugin that doesn’t run on Pages.
Fix: Either don’t link them, or commit a stub page per author with the right permalink. Pick one and be honest about it.
6. The content-statistics page renders empty
Symptom: Your stats page loads, displays a confident heading, and then… 0 posts, 0 words, 0 of everything. A dashboard for a company with no employees.
Cause: Two failures stacked: the data file isn’t delivered, and the generator that would compute the numbers is plugin-only.
Fix: Skip the stats page entirely, or commit the data file it reads and accept that the numbers are now manual.
7. The Mermaid trap
Symptom: You add jekyll-mermaid to make diagrams render. The build fails, because that plugin is not whitelisted.
Cause: You reached for a server-side plugin to do a client-side job.
Fix: Don’t add it. Render Mermaid in the browser instead — the theme already loads the JS. Write a fenced ` ```mermaid ` block and let the client draw it.
8. ai_chat and PostHog ship turned on
Symptom: A chat button that calls an endpoint that does not exist on a static host, and analytics you never signed up for, both live in production.
Cause: The theme’s defaults assume a backend. Pages has no backend.
Fix: Turn them off until you actually wire up the endpoints.
ai_chat:
enabled: false
posthog:
enabled: false
The through-line
remote_theme packs the outfit. You pack the suitcase: _config.yml, _data/, and a handful of stub pages standing in for plugins that GitHub Pages will never run. None of this is a flaw in the theme. It’s the deal you signed when you chose a static host that quarantines plugins for safety.
Every gotcha above was filed upstream as a real issue, because the next person deserves the list before the 404, not after. The full operating manual lives at /docs/autopilot/.
Pack the suitcase. The curtains were never the problem.