Question
Incremental rebuild skips pages dependent on transitive layout includes
Rahul Nea
0 reputation · 08 Nov 2025, 10:40 UTC
140.6K views
Loading…
0 reputation · 08 Nov 2025, 10:40 UTC
Jekyll's incremental regeneration mechanism caches parsed documents and rendered output keyed by file modification time and content hash, rebuilding only files whose dependencies appear changed since the last build. This design accelerates repeated builds but creates ambiguity when dependencies span transitive references.
Layout changes that affect included partials without altering the including page's metadata may not trigger reconsideration of dependent pages, because the incremental engine does not track include-level dependency chains by default. Similarly, changes to collection metadata such as output or permalink in _config.yml without file content modifications can produce inconsistent document presence in _site during incremental builds.
With no public API to inspect or manually clear the incremental cache, and the --incremental flag documented as experimental since Jekyll 3.0 with warnings about stale output, the boundaries of cache invalidation remain an unresolved design question for sites relying on transitive layout includes or collection metadata tuning. Does Jekyll reconsider pages whose included partials change without mtime updates? How does the incremental engine resolve dependency chains for collection metadata shifts in _config.yml? Is there a supported method to invalidate transitive layout dependencies without a full rebuild?
Jekyll's incremental engine does not reconsider pages when transitive includes (an include within an include) change, nor does it trigger rebuilds based on collection metadata shifts in _config.yml. Because the dependency graph only tracks direct relationships, changes to nested partials or global configuration settings often fail to invalidate the cache for dependent pages.
The incremental build mechanism relies on file modification times (mtime) and content hashes. Its behavior regarding dependencies is scoped as follows:
jekyll{% include partial.html %}, a change to that partial triggers a rebuild of the page.page.html uses layout.html, and layout.html includes partial_a.html, which in turn includes partial_b.html, a change to partial_b.html will generally not trigger a rebuild of page.html. The engine does not recursively map the entire include chain._config.yml (such as permalink or output settings for collections) are not tracked as file dependencies for individual documents. These changes are ignored during incremental runs, leading to stale output in _site.Since there is no public API to selectively flush the incremental cache, you must force a full regeneration to ensure transitive dependencies and configuration changes are applied.
Run the build command without the incremental flag or explicitly disable it to bypass the cache:
jekyll build --no-incrementalDelete the cache directory to force Jekyll to re-evaluate all hashes and dependencies from scratch:
rm -rf .jekyll-cache && jekyll buildTo verify if your specific site structure is suffering from transitive skip, perform this test:
Page → Layout → Partial A → Partial B.jekyll build --incremental to establish the initial cache.Partial B.jekyll build --incremental again. If the page output in _site does not reflect the change, the transitive dependency is being skipped.Diagnostic Note: Please specify your Jekyll version (e.g., 4.3.x). While these behaviors are standard in 4.x, dependency tracking logic has evolved since the 3.x experimental phase.
Use comments to ask for clarification. Post a solution as an answer.
5,930 reputation · 08 Nov 2025, 21:09 UTC
One boundary worth separating is direct layout references versus transitive include references. In recent Jekyll 4.x and 5.x lines, the incremental regenerator hashes the page content and its declared layout, but it does not recursively expand {% include %} tags inside that layout when computing the page's cache key. If a layout renders a partial, editing the partial updates the partial's own mtime, yet the including page remains cached because the partial is not a registered direct dependency of the page.
For collection metadata shifts, changing output or permalink in _config.yml alters what should be generated, but the incremental engine does not re-evaluate existing documents against the new configuration. The cache retains stale presence in _site.
Since there is no supported API to selectively invalidate these transitive dependencies, the practical verification is to delete the .jekyll-cache directory and rebuild. Comparing _site before and after that removal isolates whether stale output came from the incremental cache or from the build itself.