Sync Vale and markdownlint configuration from the gitlab project

Marcel Amiraultrequested to merge
docs-update-vale-rules-2026-08-19 into master

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. Configuration sync. Files changed:
    • Added doc/.vale/gitlab_base/BoldEmphasis.yml (new rule, error level: flags bold used for simple emphasis, such as **not**).
    • Updated doc/.vale/gitlab_base/OutdatedVersions.yml, OxfordComma.yml, Substitutions.yml, Uppercase.yml, and spelling-exceptions.txt.
    • Updated doc/.vale/gitlab_docs/Badges-Offerings.yml.
    • Added a lint-suppression comment to doc/.markdownlint/rules/unnecessary_traversal.js to match upstream.
  2. Documentation fixes for the new rule. Removed bold used for simple emphasis in one place, in doc/installation.md.

Not changed

These are project-specific and are deliberately left as they are:

  • doc/.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, and this project's copy is already identical to the one in the gitlab project.
  • The gitlab_release_index and gitlab_release_notes styles, and the .tmpl output templates. These are used only by the gitlab project.

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 doc reports 0 errors across 50 files.
  • markdownlint-cli2 'doc/**/*.md' reports 0 errors across 50 files.
  • 268 warning-level Vale findings remain. They are pre-existing and are not fixed here, because the docs lint CI job runs at error level.

Related links

Merge request reports