Loading
chore(lint): sync Vale configuration from the gitlab project
Syncs the Vale and markdownlint configuration in this project from the gitlab project, which is the
source of truth for those rules. The process is documented at
https://docs.gitlab.com/development/documentation/testing/#update-linter-configuration
The source of truth for this sync is gitlab commit 9d9db2d0b2302 on master (2026-08-19).
The existing gitlab_base and gitlab_docs style directories were deleted and recopied, rather than
copied over the top. This ensures rules removed upstream are also removed here. Nothing was removed
upstream this time, so no rules were deleted in this MR.
Changes
This MR has two commits:
chore(lint): sync Vale configuration from the gitlab project. Files changed:- Added
docs/.vale/gitlab_base/AlertFormat.yml. This rule was missing from this project entirely. It requires Markdown alert syntax for notes, warnings, and feature flag or disclaimer notes. - Added
docs/.vale/gitlab_base/BoldEmphasis.yml(new rule, error level: flags bold used for simple emphasis, such as**not**). - Updated
docs/.vale/gitlab_base/OutdatedVersions.yml,OxfordComma.yml,Substitutions.yml,Uppercase.yml, andspelling-exceptions.txt. - Updated
docs/.vale/gitlab_docs/Badges-Offerings.yml.
- Added
docs(lint): reword note lines to satisfy the alert format rule. Three fixes for the newly addedAlertFormatrule:docs/slack_notifications.mdis hand-written. Its**Note:**line now uses the> [!note]Markdown alert syntax.- The other two were in
docs/source/duo/cli.mdanddocs/source/repo/members/add.md, which are generated bymake gen-docsand must not be edited directly. The fix was made in the command help text they are generated from:internal/commands/duo/cli/cli.goandinternal/commands/project/members/add/long.md. In both cases theNote:prefix was dropped and the sentence left to stand on its own, because a> [!note]block would render literally in terminal help output. The generated Markdown was then refreshed withmake gen-docs.
Not changed
These are project-specific and are deliberately left as they are:
docs/.vale/gitlab_docs/RelativeLinks.yml. Configured differently in every project..vale.ini. Each project sets its ownStylesPath,IgnoredScopes,TokenIgnores, andBasedOnStyles..markdownlint-cli2.yaml. No rule changes were needed. This project's local overrides (ol-prefix,commands-show-output, theno-trailing-punctuationcharacter set, and the templateignores) are intentional and are kept.- The
gitlab_release_indexandgitlab_release_notesstyles, and the.tmploutput templates. These are used only by thegitlabproject. docs/.vale/gitlab_docswas refreshed for consistency, but.vale.iniin this project setsBasedOnStyles = gitlab_baseonly, so those rules do not currently run.
Testing
- Ran Vale 3.14.1 and markdownlint-cli2 0.22.1 locally, matching the versions in this project's docs lint image.
vale --minAlertLevel error docsreports 0 errors across 304 files.markdownlint-cli2 'docs/**/*.md' *.mdreports 0 errors across 311 files.- No test asserts on the changed help text.
- 255 warning-level Vale findings remain. They are pre-existing and are not fixed here, because the docs lint CI job runs at error level.