Sync Vale and markdownlint 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. Configuration sync. Files changed:
    • 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.
    • Added a lint-suppression comment to docs/.markdownlint/rules/unnecessary_traversal.js to match upstream.
  2. Documentation fixes for the new rule. Removed bold used for simple emphasis in six places across five files: docs/commands/_index.md, docs/configuration/autoscale.md, docs/executors/docker.md, docs/faq/_index.md, and docs/install/windows.md.

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 copy differs from the gitlab project only in the doc/ to docs/ path for its custom rule, which is intentional.
  • 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 docs reports 0 errors across 68 files.
  • markdownlint-cli2 "docs/**/*.md" reports 0 errors across 68 files.
  • 366 warning-level Vale findings remain. They are pre-existing and are not fixed here, because the docs:lint markdown CI job runs at error level.

Merge request reports

Loading
Loading