Markdown

Links and References

• Use descriptive link text.
• Link the first meaningful mention of a tool or spec when it helps orientation.
• Avoid dumping raw URLs in the middle of prose unless the URL itself matters.

Tables

• Use tables for compact comparisons or matrices.
• Keep cell text short.
• Prefer bullets or sections when explanations are longer than a phrase.

Readability

• Keep documents scannable.
• Prefer explicit names over shorthand.
• Avoid decorative formatting that does not add structure.
• When editing an existing doc, preserve local style unless it blocks readability or lint compliance.

Rumdl

Install

uv tool install rumdl

Common Commands

uv run rumdl check .
uv run rumdl check --fix .
uv run rumdl fmt .
uv run rumdl init

Recommended .rumdl.toml

[global]
disable = ["MD013", "MD033"]
exclude = ["node_modules", "dist", "build", "target"]
respect_gitignore = true

[MD003]
style = "atx"

[MD007]
indent = 4

[MD060]
enabled = true
style = "aligned"

Usage Notes

• Use check in CI and validation flows.
• Use check --fix when the repo accepts automatic Markdown rewrites.
• Use fmt when you want formatting without applying other lint fixes.
• Keep config close to the repo root unless the project already centralizes it elsewhere.

Rules of Thumb

• Follow existing repo Markdown style before introducing new structure.
• Use reference files for detailed policy; keep top-level docs focused.

Related

• skills/documentation/SKILL.md -- README structure, ADRs, changelogs
• rules/documentation.md -- always-on Markdown conventions