Jekyll `--incremental` flag and watch-mode staleness

Short answer

--incremental does not decide freshness purely from file modification timestamps. Jekyll maintains regeneration metadata (a dependency map between source files and the pages they affect) and regenerates only files whose content — or whose known dependencies — changed. Touching a file without changing its content generally does not trigger regeneration. A full rebuild is forced when the metadata cache is missing or deleted, when the process restarts without a readable cache, or when you run without --incremental. Editing config files is a known stale-output case: restart with a full build after changing them.

Confirmed vs. likely

Confirmed behavior (well-established across Jekyll 3.x/4.x):

• Incremental mode serializes a regeneration cache (commonly .jekyll-metadata or under .jekyll-cache/, depending on version) and uses it to skip unchanged documents on rebuild.
• Multiple config files passed via --config _config.yml,_config_dev.yml are merged, later files taking precedence. However, the incremental tracker does not reliably treat config edits as a dependency of every page, so config changes can silently fail to propagate.
• Deleting the cache directory/file guarantees the next build is a full regeneration.

Likely explanation for observed staleness: dependency tracking is best-effort. Dynamic Liquid includes, data-driven loops, and plugin- or generator-injected content often don't register dependencies, so their output stays stale until a full build. Separately, watch-mode staleness can come from the listen watcher missing events (symlinks, NFS, Docker bind mounts) — a different root cause than incremental logic.

What to do in your case

1. After editing _config.yml or any secondary config, stop the server and rebuild fully:

   rm -rf .jekyll-cache .jekyll-metadata
   bundle exec jekyll serve --incremental

2. If you suspect plugin-injected content is stale, same remedy: delete the cache and rebuild.
3. If file edits aren't triggering rebuilds at all (containers/VMs), add --force_polling.
4. Never use --incremental for production builds.

Verify it yourself

Run jekyll serve --incremental, edit one post, and check _site output timestamps — only that page and dependents (index, feeds) should update. Then edit a config value, observe whether it appears, delete the cache, and compare. Check jekyll --version, since cache location and incremental details differ between 3.x and 4.x.

One missing detail that would change this advice: your Jekyll version and whether the stale content comes from a plugin — if so, the fix is a full rebuild habit, not watcher tuning.