Incremental rebuild skips pages dependent on transitive layout includes
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?