The build that died on an unknown tag

The first build of this site failed in 39 seconds.

That is fast. We launched, pushed, and were rewarded almost immediately with a red X. Efficient. The error:

Liquid Exception: Liquid syntax error (line 56): Unknown tag 'include_cached'
in /_layouts/root.html

We had not written /_layouts/root.html. We had never opened it. It is a theme file — it ships inside zer0-mistakes, lives somewhere in the remote theme gem, and we inherited it sight unseen. The build broke on a line of code we had never read, in a file we did not have, over a tag we did not recognize.

This is the normal first-build experience. Welcome.

What include_cached actually is

include_cached is not built-in Liquid. Jekyll ships include. It does not ship include_cached. That tag comes from a plugin: jekyll-include-cache. Many popular themes use it to avoid re-rendering the same nav partial 400 times, which is a reasonable thing to want.

The theme’s layouts depend on it. The theme assumes it is there.

It was not there.

The rule everyone forgets

Here is the mental model that would have saved us 39 seconds:

Remote themes ship layouts, not plugins.

When you set remote_theme: bamr87/zer0-mistakes, you get the theme’s _layouts, _includes, _sass, and assets. You do not automatically get the plugins those layouts call. A layout can write {% include_cached nav.html %} all it likes, but the tag only exists if your _config.yml enables the plugin that defines it. The theme cannot enable a plugin on your behalf. That is your job.

So the theme handed us a layout that calls a tag, and never handed us the tag.

The fix (one line, technically four)

Add the plugin to your own plugins list in _config.yml:

plugins:
  - jekyll-include-cache

That is the whole fix for the actual error. While we were in there, we added three more that the theme expects and that we wanted anyway:

plugins:
  - jekyll-include-cache
  - jekyll-relative-links
  - jekyll-redirect-from
  - jekyll-paginate

No Gemfile change. None. All four are on the GitHub Pages plugin whitelist, which means the Pages build environment already has them installed — you just have to tell it to load them. On Pages, the plugins: list is a request to turn on something already present, not an instruction to install something new.

Build #2 went green in 41 seconds.

The trap: do not also add jekyll-mermaid

You will be tempted. The theme renders Mermaid diagrams, you will see mermaid in a code fence, and your instinct will be to reach for the plugin. Resist.

jekyll-mermaid is not on the Pages whitelist. Adding it does not fix anything; it breaks the build a second time, now with a different error, and you will have traded one red X for another. The theme does not need it: it renders Mermaid client-side, in the browser, with JavaScript, after the page has already shipped. The diagram is drawn on the reader’s machine, not the build server. Nothing to install. Leave it alone.

# Do NOT add this. It will break the build.
# plugins:
#   - jekyll-mermaid

How to actually read the log

The red X tells you nothing. Do not stop there.

1. Open the failed run — the pages-build-and-deployment workflow.
2. Click into the failed step (the one with its own red X), not the green ones above it.
3. Scroll to the bottom. Find the last Liquid Exception line. The last one is usually the real one; everything above is the build politely warming up before it falls over.
4. Look at the Annotations box near the top of the run summary. It pulls out the file and line for you — in our case, /_layouts/root.html, line 56 — so you do not have to.

That sequence turns “it’s broken” into “it’s broken here, because of this,” which is the entire game.

The borrowed-tuxedo problem

A remote theme is a borrowed tuxedo. It fits, it looks sharp, and it does not come with cufflinks. The jacket assumes you own cufflinks. The jacket is correct to assume this — most people do — but it cannot reach into your drawer and put them on for you.

jekyll-include-cache was the cufflinks. One line of config, and the outfit was complete.

We are filing the residual gaps upstream as issues — the theme could note its plugin dependencies in its README so the next person does not spend their 39 seconds the way we spent ours. That is not the theme’s failure so much as a missing sentence. The cufflinks were always a one-line config away. Someone just needs to mention they exist.