# Docs Markdown Linting (rumdl) (https://jackin.tailrocks.com/roadmap/docs-markdown-linting/)



**Status**: Open — adoption plan drafted, no implementation committed; no rumdl config, CI step, or `check:md` script exists in the repo yet

## Shipped baseline [#shipped-baseline]

The docs site has automated gates for structural breakage (the Fumadocs build), broken links (lychee, via <RepoFile path="docs/lychee.toml">docs/lychee.toml</RepoFile>), code-span references to real repo files (`cargo xtask docs repo-links`), and roadmap sidebar completeness (`cargo xtask roadmap audit`). The Rust validators live in <RepoFile path="crates/jackin-xtask/src/docs.rs">crates/jackin-xtask/src/docs.rs</RepoFile>. None of these check mechanical markdown style — heading hierarchy, code-fence languages, list-marker consistency, line length, emphasis-marker mixing. No `.rumdl.toml`, no rumdl CI step in <RepoFile path=".github/workflows/docs.yml">.github/workflows/docs.yml</RepoFile>, and no `check:md` script in <RepoFile path="docs/package.json">docs/package.json</RepoFile> exist today — this item is fully unstarted.

Research: [Docs markdown linting: rumdl adoption rationale](/reference/research/documentation/docs-markdown-linting/) covers why rumdl over `markdownlint-cli2`/`remark-lint`/`mado`, and the trade-offs of adopting it.

## Remaining work [#remaining-work]

1. **Pin the binary.** Add a SHA-pinned `rvben/rumdl@<sha>` step to <RepoFile path=".github/workflows/docs.yml">.github/workflows/docs.yml</RepoFile>, between checkout and the repo-links check; add a matching local `bun run check:md` script.
2. **Author `docs/.rumdl.toml`.** Start from the default rule set, then disable rules that conflict with Fumadocs conventions (`MD057` relative-link existence — fires on site-absolute routes that lychee already covers; `MD041` first-line H1 — Fumadocs renders titles from frontmatter; `MD013` line length — relax to 120 with code-blocks/tables excluded). Audit `MD033`/`MD025`/`MD026` once a dry run produces a real violation list.
3. **Cleanup pass.** Run `rumdl check --fix` against `docs/content/docs/`, hand-fix what `--fix` cannot resolve, and land the cleanup, the config, and the CI step together — a half-adopted state (linter present but non-blocking) is worse than not adopting yet.
4. **Wire into docs CI.** Add the rumdl step beside `check:repo-links`, `check:roadmap-sidebar`, build, and link checking in the docs workflow. Required-check/branch-protection configuration is an operator-side repository setting, not something this item can assert.
5. **Renovate coverage.** Confirm Renovate's rules pick up the new `rvben/rumdl@<sha>` pin so version bumps land as routine PRs.

## Related work [#related-work]

* Research: [Docs markdown linting: rumdl adoption rationale](/reference/research/documentation/docs-markdown-linting/) — why rumdl, alternatives rejected, open design questions.
* <RepoFile path=".github/workflows/docs.yml">.github/workflows/docs.yml</RepoFile> — CI integration point for the rumdl step.
* <RepoFile path="crates/jackin-xtask/src/docs.rs">crates/jackin-xtask/src/docs.rs</RepoFile> — existing custom-rule precedent rumdl complements, not replaces.
* <RepoFile path="docs/lychee.toml">docs/lychee.toml</RepoFile> — companion link-check gate.