Jekyll Incremental Builds: Diagnosing Stale Output When Edited Files Are Not Regenerated

The symptom: edits disappear into the cache

You change a Markdown post or a layout, run your normal build or serve command, and the generated site in _site still shows the old content. The command exits successfully, but the file you edited was never rewritten. In Jekyll 4.x and later, this almost always means the incremental build cache is out of sync with your source tree, or incremental mode was never actually engaged.

Useful takeaway: before deleting anything, confirm that --incremental is present on the command line, then inspect .jekyll-cache. A full jekyll clean is the last resort, not the first step.

Cause and diagnostic table

Observable condition	Likely cause	First check
Edited file missing from _site after jekyll build	incremental: true in _config.yml but --incremental absent from the command	Run jekyll build --incremental --verbose and read the log
Build succeeds, but _site timestamps are older than source files	Stale or corrupted .jekyll-cache metadata	List .jekyll-cache/Jekyll/Cache and compare modification times
Incremental processing stops after a warning	Plugin deprecation or missing dependency aborts the incremental pass	Run jekyll build --incremental --trace and read the full output

Ordered checks and fixes

1. Confirm incremental mode is active in both places

Jekyll does not turn on incremental builds from _config.yml alone when you invoke jekyll build. The command-line flag --incremental must be supplied. Conversely, jekyll serve --incremental enables it for that session even if the config file is silent.

Run this in your project root (normal user permissions are sufficient):

jekyll build --incremental --verbose

Expected check: the log should reference cache reads and indicate that only changed documents are being rendered. If the output looks like a full site build with no cache activity, the flag was not honored.

Fix: add --incremental to your build script, CI step, or jekyll serve invocation. If you expected the config key to be enough, remove the ambiguity by always passing the flag explicitly.

2. Inspect the cache directory for stale entries

Jekyll 4.x stores incremental metadata under .jekyll-cache/. If that directory is missing, empty, or contains files with timestamps frozen in the past while your sources are newer, the cache is not tracking changes.

On Linux or macOS, run:

ls -la .jekyll-cache/Jekyll/Cache

On Windows PowerShell, run:

Get-ChildItem .jekyll-cache\Jekyll\Cache

Expected check: cache files should have recent modification times when you edit source files. Zero-byte files or a completely empty directory indicate corruption.

Fix: run jekyll clean to remove .jekyll-cache and _site, then rebuild with jekyll build --incremental. Risk: this is destructive to generated output. The first rebuild after a clean is a full build and will take longer than an incremental one. Do not run it directly against a production deploy directory without a backup.

3. Read the complete console output for aborted processing

Some plugins that hook into Jekyll’s rendering pipeline can skip incremental regeneration or emit deprecation warnings that stop the incremental pass before it finishes. A truncated log often hides the real failure.

Run:

jekyll build --incremental --trace

Expected check: no Ruby exceptions, gem load errors, or warnings that name a plugin immediately before the build stops rendering changed files.

Fix: if a specific plugin appears in the warning path, temporarily remove it from the plugins: array in _config.yml, rebuild, and confirm regeneration returns. If it does, look for a plugin release that explicitly supports Jekyll 4.x incremental builds, or fall back to full builds for that site.

4. Verify regeneration with file timestamps

A quick behavioral test tells you whether incremental mode is truly working. Touch a source file and rebuild, then compare timestamps in _site.

On Linux or macOS:

touch path/to/your-post.md && jekyll build --incremental

On Windows PowerShell:

(Get-Item path\to\your-post.md).LastWriteTime = Get-Date; jekyll build --incremental

Expected check: only the changed document and any layouts or includes it depends on should be rewritten. Unrelated files in _site should keep their original timestamps. If every file is rewritten, incremental mode is not active. If nothing is rewritten, return to checks 2 and 3.

Escalation criteria

Consider filing an issue when:

• You have run jekyll clean, confirmed --incremental is present, and the edited file still does not appear in _site.
• The failure reproduces on a minimal site with no plugins and a default configuration.
• A single plugin consistently prevents regeneration across multiple Jekyll 4.x releases.

When you escalate, gather the exact Jekyll version (jekyll --version), Ruby version, the full --trace output, a minimal _config.yml, and the output of bundle list. File the report against the Jekyll repository for core cache issues, or the plugin repository if a plugin is implicated.

Limitations and practical verification

These steps assume Jekyll 4.0 or newer. Jekyll 3.x uses a different cache layout, so the .jekyll-cache paths described here will not match. Some community plugins are fundamentally incompatible with incremental builds and require a full build for correctness; disabling incremental mode entirely may be the only stable option for those sites.

To verify a fix, run jekyll serve --incremental, edit a post in your editor, and confirm the browser updates without a full rebuild message. Then check the timestamp of the corresponding file in _site: it should be newer than before, while unrelated output files remain untouched.