You might think jekyll-include-cache caches every page, but it actually only takes a “snapshot” cache of individual include files, which falls far short of expectations.

Because Jekyll builds can be painfully slow, AI chat tools often recommend the jekyll-include-cache plugin to avoid the slow down caused by repeatedly rendering include files.

After making the change and publishing, I didn’t notice any issues at first. Later, when I visited the site using a browser I rarely use, I noticed things looked a bit off: sidebars had vanished across all pages, and custom large-screen layouts had shrunk and become completely messed up. At first, I assumed it was a browser compatibility issue. Soon after, I realized that every page was outputting the exact same title. Checking it in my regular browser ruled out any style compatibility issues. What a massive blunder! Initially, I couldn’t figure out why, and AI chat was about as helpful as taking me “to infinity and beyond.” After countless trial-and-error commits and comparisons, I suddenly remembered changing include to include_cached. Reverting that change fixed everything instantly. Because many include files across the site rely heavily on conditional logic and variables, using jekyll-include-cache essentially rendered everything “static”—every page ended up with the identical title, and custom pages lost their unique styles, defaulting to shared ones instead.

Let’s simplify a real-world scenario with a quick case study to understand how jekyll-include-cache actually works under the hood:

Assume every page on your Yijile.com site uses the default.html layout (layout: default), and inside default.html, you include _includes/title.html and _includes/css.html:

_layouts/default.html

1
2

{% include title.html -%}
{% include css.html -%}

_includes/title.html

Expected result: The output <title> dynamically changes based on the specific page.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{%- include happylife/page_css.html -%}
{% if page.site_title %}
<title>{{ page.title }}{% if page.parent %} - {{ page.parent }}{% endif %} - {{ page.site_title }}</title>
{% seo title=false %}
{% elsif page.site_title == false %}
<title>{{ page.title }}{% if page.parent %} - {{ page.parent }}{% endif %}</title>
{% seo title=false %}
{% else %}
    {% seo %}
{% endif %}

_includes/css.html

Expected result: The showcase page injects styles from the showcase.scss file.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{%- assign showcase = "scss/showcase.scss" -%}

{%- capture showcase %}
  {% include {{ showcase }} %}
{% endcapture -%}
{%- case page.url %}
  {%- when "/showcase/" %}
    <style>
        {{ showcase | scssify }}
    </style>
  {%- else -%}
{%- endcase -%}

Once you change include to include_cached, Jekyll caches the rendered output of title.html and css.html the very first time they are processed on a page. For all subsequent pages, Jekyll skips rendering and simply reuses that initial cached result. So, if the first page processed happened to be the homepage, every other page using title.html would suddenly inherit the homepage title.

_layouts/default.html

1
2

{% include_cached title.html -%}
{% include_cached css.html -%}

Ultimately, every page utilizing title.html and css.html ended up rendering this:

1

<title>首页</title>

Seeing this happen for the first time completely blew my mind. Compared to CMS platforms like DedeCMS, WordPress, or Typecho, jekyll-include-cache completely falls short of expectations. So, can we still use jekyll-include-cache and include_cached?

The answer is yes, absolutely.

The official documentation demonstrates passing data from the outside, but it doesn’t clearly cover passing dynamic variables, so use that with caution.

External file:

1

{% include_cached shirt.html size=medium color=red %}

Include file:

1

Buy our {{ include.color }} shirt in {{ include.size }}!

Recommendation: Stick to using it exclusively for include files that contain no conditional logic and no variables.

转载请注明转自：Yijile.com（ https://yijile.com/en/defects-in-jekyll-include-cache/ ）

本文采用 CC BY-NC-SA 4.0方式授权。
转载请注明出处和本文链接，说明是否进行修改，不得用于商业用途，使用相同方式共享。