Docs Markdown Linting (rumdl)

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

Shipped baseline

The docs site has automated gates for structural breakage (the Fumadocs build), broken links (lychee, via docs/lychee.toml), 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 crates/jackin-xtask/src/docs.rs. 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 .github/workflows/docs.yml, and no check:md script in docs/package.json exist today — this item is fully unstarted.

Research: Docs markdown linting: rumdl adoption rationale covers why rumdl over markdownlint-cli2/remark-lint/mado, and the trade-offs of adopting it.

Remaining work

1. Pin the binary. Add a SHA-pinned rvben/rumdl@<sha> step to .github/workflows/docs.yml, 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

• Research: Docs markdown linting: rumdl adoption rationale — why rumdl, alternatives rejected, open design questions.
• .github/workflows/docs.yml — CI integration point for the rumdl step.
• crates/jackin-xtask/src/docs.rs — existing custom-rule precedent rumdl complements, not replaces.
• docs/lychee.toml — companion link-check gate.