This page describes the tools, configuration files, and CI workflow that enforce documentation quality standards across all Markdown files in the revive repository. It covers three distinct concerns: Markdown formatting rules (markdownlint-cli2), table-of-contents consistency (markdown-toc), and code snippet formatting (mdsf).
For information about Go code quality standards applied during development, see the CI/CD pipeline (page 7.3) and the build system (page 7.2).
Three tools work together to keep the documentation well-formed:
| Tool | Purpose | Config File |
|---|---|---|
markdownlint-cli2 | Enforces Markdown formatting rules (line length, blank lines, heading style, etc.) | .markdownlint-cli2.yaml |
markdown-toc | Regenerates and verifies the table of contents in README.md and RULES_DESCRIPTIONS.md | (CLI flags only) |
mdsf | Formats fenced code blocks inside Markdown files using language-specific formatters | mdsf.json |
All three are executed together in the lint-md CI job defined in .github/workflows/lint-md.yaml
Scope of files checked: All *.md files matched by the glob pattern "*.md" defined in .markdownlint-cli2.yaml32-33
Diagram: lint-md.yaml job steps and their tool dependencies
Sources: .github/workflows/lint-md.yaml1-74
The configuration file is .markdownlint-cli2.yaml
All markdownlint rules are enabled by default (default: true). The following rules are explicitly tuned:
| Rule | Setting | Effect |
|---|---|---|
MD010 (no-hard-tabs) | code_blocks: false | Hard tabs are permitted inside fenced code blocks |
MD013 (line-length) | line_length: 150, code_block_line_length: 200 | Relaxed limits for prose and code blocks |
MD033 (no-inline-html) | false (disabled) | Inline HTML is permitted |
MD055 (table-pipe-style) | false (disabled) | Table pipe style is not enforced |
MD060 (table-column-style) | false (disabled) | Table column alignment is not enforced |
| Setting | Value | Effect |
|---|---|---|
fix | false | Tool reports errors but does not auto-fix |
globs | ["*.md"] | Matches only top-level *.md files |
noBanner | true | Suppresses the tool's banner message |
showFound | true | Prints the list of discovered files |
Sources: .markdownlint-cli2.yaml1-37
markdown-toc regenerates the table of contents in-place (-i) and then git diff --exit-code confirms the file was not changed (i.e., the existing TOC was already correct). If the TOC is stale, the diff step fails the CI job.
Diagram: TOC verification logic
The two files have different --maxdepth values because README.md documents deeply nested sections (up to depth 4), while RULES_DESCRIPTIONS.md uses a shallower structure (depth 2).
Sources: .github/workflows/lint-md.yaml61-63 DEVELOPING.md126-131
mdsf reads fenced code blocks in Markdown files and routes each block to a formatter based on the language identifier of the fence. The configuration is in mdsf.json
Sources: mdsf.json1-13
| Key | Value | Meaning |
|---|---|---|
format_finished_document | false | Does not run a whole-document formatter after block formatting |
languages.go | "goimports" | Go blocks formatted with goimports |
languages.shell | "shfmt" | Shell blocks formatted with shfmt |
languages.toml | "taplo" | TOML blocks formatted with taplo |
language_aliases.bash | "shell" | bash fence label routes to the shell formatter |
language_aliases.sh | "shell" | sh fence label routes to the shell formatter |
Sources: mdsf.json1-13
In CI, mdsf is run in verify mode:
mdsf verify --on-missing-language-definition ignore --on-missing-tool-binary fail-fast .
--on-missing-language-definition ignore: blocks with unrecognized language labels are skipped silently.--on-missing-tool-binary fail-fast: if a required formatter binary is absent, the step fails immediately.If mdsf verify fails, the workflow runs mdsf format --debug ... followed by git diff --exit-code to display the exact diffs that represent unformatted code blocks.
Sources: .github/workflows/lint-md.yaml65-73
When a Go code snippet is intentionally non-compilable (e.g., a partial snippet illustrating a pattern), the golang language label should be used instead of go. This prevents goimports from being invoked on the block and failing. However, the project preference is to use go with compilable snippets whenever possible.
Sources: DEVELOPING.md143-145
The lint-md CI job installs each tool before running checks. The table below maps each tool to its install source:
| Tool | Install Method | Source in CI |
|---|---|---|
mdsf | hougesen/mdsf@v0.11.1 GitHub Action | .github/workflows/lint-md.yaml31-32 |
goimports | go install golang.org/x/tools/cmd/goimports (via tools/ module) | .github/workflows/lint-md.yaml34-37 |
shfmt | go install mvdan.cc/sh/v3/cmd/shfmt (via tools/ module) | .github/workflows/lint-md.yaml39-42 |
taplo | curl download of the 0.10.0 Linux binary | .github/workflows/lint-md.yaml44-45 |
markdownlint-cli2 | DavidAnson/markdownlint-cli2-action@v22 GitHub Action | .github/workflows/lint-md.yaml55-58 |
markdown-toc | npm install -g markdown-toc | .github/workflows/lint-md.yaml52-53 |
goimports and shfmt are installed using the tools/ working directory so their versions are pinned by tools/go.mod. See page 7.2 for details on the tools/ module.
Sources: .github/workflows/lint-md.yaml1-74 DEVELOPING.md103-109
The full sequence of commands to reproduce CI checks locally is documented in DEVELOPING.md103-145
Step 1 — Markdown formatting:
markdownlint-cli2 .
The tool automatically discovers and applies .markdownlint-cli2.yaml
Step 2 — TOC verification:
Step 3 — Code snippet verification:
Step 3 (fix mode):
Sources: DEVELOPING.md109-145
Refresh this wiki