Jekyll Incremental Regeneration Stale Output Diagnostic Guide

Edits not appearing in _site with incremental regeneration on

Jekyll builds finish in seconds after you change a post, collection document, or include, but the generated _site output does not change. Some pages update while related pages do not, and renaming or moving files can make pages disappear from the build. This is the classic symptom of incremental regeneration cache drift.

Incremental regeneration is a Jekyll feature that skips unchanged files by tracking a dependency graph in .jekyll-cache. When the graph is incomplete or stale, Jekyll believes nothing needs rebuilding.

Recognizable condition

• Local edit to _posts, _collections, _includes, or layouts produces no change in _site, or _site files keep old modification times.
• Build log shows fast completion with messages about incremental regeneration and a cache path.
• Partial updates: a changed include updates one page but not all pages that use it.
• After renaming a file or moving it between collections, the old URL remains and the new URL is missing.
• Build succeeds locally with incremental on but behaves differently on CI, or vice versa.

Cause diagnostic table

Symptom	Likely cause	Why it happens
Stale pages after edit, fast build	Incremental cache missing dependency	Dependency graph did not record a relationship between source and output.
Pages missing after rename or move	Stale dependency graph	Old source path remains in cache; new path not tracked.
Fast build with no output change	Cache out of sync with filesystem	Modification times or file system events not detected correctly.
Local vs CI difference	Config or plugin parity issue	incremental setting, safe mode, or plugins differ; incremental support varies by plugin.

Ordered checks

1. Confirm incremental is enabled

Run from project root with read access to the repo.

cat _config.yml | grep -i incremental

Expected check: look for incremental: true or absence of incremental: false. Incremental defaults to off in some setups and on in jekyll serve --incremental.

2. Inspect build logs and cache path

jekyll build --verbose

Run in a terminal at project root. Required permissions: read source, write _site and .jekyll-cache. Check log for incremental regeneration messages and the cache directory path, typically .jekyll-cache.

3. Compare timestamps

stat -c '%y %n' _site/index.html

On macOS use stat -f '%Sm %N'. Compare the modification time to the source file you edited. If _site is older than the source and incremental is on, the dependency was not triggered.

4. Verify collection and front matter consistency

Check that collections have output: true where expected and that front matter defaults are not changing output paths between builds. Inconsistent defaults can break dependency tracking.

5. Isolate with incremental disabled

jekyll build --incremental false

Run once with incremental disabled. If the output now reflects your edit, the issue is incremental cache behavior, not source content.

Fixes tied to findings

Cache is stale or out of sync

Clear the cache to force a full dependency rebuild. This changes state.

rm -rf .jekyll-cache

Run at project root. Then run a clean build:

jekyll build

Risk: next build will be full and slower for large sites. Re-enable incremental only after verifying stable output.

Renamed or moved files

Run one full build after any rename or move to rebuild the graph. Do not rely on incremental for structural changes.

jekyll build --incremental false

Rollback: if you need incremental for development, set it back in _config.yml after the clean build.

Development workflow

Set incremental off for active development on sites with dynamic includes or generators:

# _config.yml

incremental: false

Risk: build times increase significantly for large sites. Use only after validation.

Plugin and Liquid compatibility

Avoid plugins that generate pages dynamically or read external data during build. These can break incremental dependency tracking and cause silent stale output. Ensure custom generators declare dependencies explicitly if they modify collections during build.

Escalation criteria

• Persistent stale output after clearing .jekyll-cache and running a full build with incremental disabled.
• Errors referencing missing dependencies or Liquid syntax in includes that only appear with incremental on.
• Build differences between local and CI persist after normalizing _config.yml settings for incremental, collections, and plugins, and after matching safe mode.
• Custom generators or plugins modify collections during build. Incremental support requires explicit dependency declarations and is version sensitive between Jekyll 3.x and 4.x.

Limitations and verification

Incremental regeneration behavior is version sensitive in Jekyll 3.x versus 4.x and may differ with Ruby versions and operating systems. File system timestamp resolution can cause missed changes on network drives.

Practical verification:

1. Run jekyll build --verbose with incremental enabled and disabled and compare _site timestamps for changed files.
2. Clear .jekyll-cache, perform a clean build, then repeat the same edit to confirm output changes consistently.
3. Compare local _config.yml settings for incremental, collections, and plugins against the CI environment to ensure parity.

Do not assume incremental is safe for production builds. Use full builds for releases.