ci: add markdown linting with markdownlint, Vale, and lychee

Summary

Adds documentation linting to the repo, following the same patterns used by the GitLab handbook and docs-gitlab-com repos.

Three linters, each with a specific job:

  • markdownlint-cli2 (0.19.0) -- structural markdown checks. Config in .markdownlint-cli2.jsonc. Checks fenced code blocks, ATX headings, line length limits (5000 for prose, 100 for headings), duplicate headings (siblings only), and trailing punctuation. Ignores target/, node_modules/, helm-dev/, and CHANGELOG.md.
  • Vale (3.13.0) -- prose quality. Config in .vale.ini, rules in .vale/gitlab_base/. Uses 8 rules from GitLab's shared gitlab_base style: inclusive language, default branch terminology, merge conflict markers, heading links, heading depth, EOL whitespace, multi-line links, and non-standard quotes.
  • lychee (0.21.0) -- broken link detection. Config in lychee.toml. Runs offline fragment checking. Excludes private domains (ops.gitlab.net, internal.gitlab.com, etc.) and build directories.

All three tools are version-pinned in mise.toml. New mise tasks:

mise run lint:markdown    # markdownlint
mise run lint:vale        # Vale prose checks
mise run lint:links       # lychee link checking
mise run lint:docs        # all three

What changed

  • .markdownlint-cli2.jsonc -- markdownlint config
  • .vale.ini + .vale/gitlab_base/*.yml -- Vale config and 8 GitLab base rules
  • lychee.toml -- link checker config
  • mise.toml -- tool versions + lint tasks

Test plan

  • Run mise install to install the new tools
  • Run mise run lint:markdown and verify it passes or reports real issues
  • Run mise run lint:vale and verify it catches inclusive language / merge conflicts
  • Run mise run lint:links and verify it checks fragment links
  • Run mise run lint:docs to confirm all three run together
Edited by Michael Angelo Rivera

Merge request reports

Loading