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. Ignorestarget/,node_modules/,helm-dev/, andCHANGELOG.md. -
Vale (3.13.0) -- prose quality. Config in
.vale.ini, rules in.vale/gitlab_base/. Uses 8 rules from GitLab's sharedgitlab_basestyle: 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 installto install the new tools -
Run
mise run lint:markdownand verify it passes or reports real issues -
Run
mise run lint:valeand verify it catches inclusive language / merge conflicts -
Run
mise run lint:linksand verify it checks fragment links -
Run
mise run lint:docsto confirm all three run together
Edited by Michael Angelo Rivera