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:

  1. 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, and spelling-exceptions.txt.
    • Updated docs/.vale/gitlab_docs/Badges-Offerings.yml.
  2. docs(lint): reword note lines to satisfy the alert format rule. Three fixes for the newly added AlertFormat rule:
    • docs/slack_notifications.md is hand-written. Its **Note:** line now uses the > [!note] Markdown alert syntax.
    • The other two were in docs/source/duo/cli.md and docs/source/repo/members/add.md, which are generated by make gen-docs and must not be edited directly. The fix was made in the command help text they are generated from: internal/commands/duo/cli/cli.go and internal/commands/project/members/add/long.md. In both cases the Note: 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 with make 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 own StylesPath, IgnoredScopes, TokenIgnores, and BasedOnStyles.
  • .markdownlint-cli2.yaml. No rule changes were needed. This project's local overrides (ol-prefix, commands-show-output, the no-trailing-punctuation character set, and the template ignores) are intentional and are kept.
  • The gitlab_release_index and gitlab_release_notes styles, and the .tmpl output templates. These are used only by the gitlab project.
  • docs/.vale/gitlab_docs was refreshed for consistency, but .vale.ini in this project sets BasedOnStyles = gitlab_base only, 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 docs reports 0 errors across 304 files.
  • markdownlint-cli2 'docs/**/*.md' *.md reports 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.

Merge request reports

Loading
Loading