doctoc / markdown-toc table of contents out of date in CI

By Kaveh Alemi·Latchkey

A CI step regenerates the table of contents with doctoc or markdown-toc and compares it to the committed file. When headings changed but the TOC was not regenerated, the diff is non-empty and the job fails.

What this error means

The docs job fails after running doctoc, with git showing the TOC section changed, or a message like "TOC is out of date, run doctoc and commit".

$ doctoc README.md
"README.md" will be updated
$ git diff --exit-code README.md
diff --git a/README.md b/README.md
@@ <!-- START doctoc -->
-  - [Old Heading](#old-heading)
+  - [New Heading](#new-heading)
Error: Process completed with exit code 1.

Common causes

Headings changed without regenerating the TOC

Someone edited section headings but did not re-run doctoc, so the committed TOC no longer matches the document.

A different tool or version generated the TOC

doctoc and markdown-toc slugify and format differently; switching tools or versions produces a diff even without content changes.

How to fix it

Regenerate the TOC and commit

1. Run the same TOC tool CI uses.
2. Commit the regenerated section.
3. Re-run so the check-only diff is empty.

npx doctoc README.md --github
git add README.md

Pin the tool and check with git diff

Pin the version and gate on a clean diff so the TOC stays deterministic across contributors.

- run: npx doctoc@2 README.md --github
- run: git diff --exit-code README.md

How to prevent it

• Regenerate the TOC in a pre-commit hook whenever headings change.
• Pin the TOC tool and version so output is deterministic.
• Gate on git diff --exit-code so a stale TOC fails clearly.

Frequently asked questions

Related guides

References

• GitHub Actions documentation