Sync Vale and markdownlint configuration to documentation source projects

Sync Vale and markdownlint configuration

Vale and markdownlint configuration is stored in each documentation source project separately. The gitlab project is the source of truth. All rule changes are made there first, then copied out to the other projects.

The copies drift from the source of truth over time, as changes land in gitlab but aren't copied downstream right away. This issue tracks a periodic resynchronization of that configuration.

The process is documented at https://docs.gitlab.com/development/documentation/testing/#update-linter-configuration.

Each project's copy of a style directory is deleted before the new one is copied in. This means rules deleted upstream are also removed downstream. A plain copy would leave stale, deleted rules behind.

The source of truth for this round is gitlab commit 9d9db2d0b2302 on master (2026-08-19).

Changes being synced

• New rule added: gitlab_base/BoldEmphasis.yml. This rule is missing from all six projects.
• Changed rules, present in all six projects: gitlab_base/OutdatedVersions.yml, gitlab_base/OxfordComma.yml, gitlab_base/Substitutions.yml, gitlab_base/Uppercase.yml, gitlab_base/spelling-exceptions.txt.
• Changed rule, affecting charts/gitlab, cli, and artifact-registry only: gitlab_base/AlertFormat.yml. This rule is missing entirely from cli.
• Changed rule, affecting the five projects that use it: gitlab_docs/Badges-Offerings.yml.
• No rules were deleted upstream since the last sync, so no rules are removed this time.
• The markdownlint configuration in .markdownlint-cli2.yaml needs no rule changes in any project. The only markdownlint change is a one-line lint-suppression comment in the custom rule file .markdownlint/rules/unnecessary_traversal.js. This affects gitlab-runner, omnibus-gitlab, charts/gitlab, and gitlab-operator.

Files not synced

These files are project-specific and are deliberately left alone:

• gitlab_docs/RelativeLinks.yml. Each project configures this rule differently.
• .vale.ini. Each project sets its own StylesPath, IgnoredScopes, TokenIgnores, and BasedOnStyles.
• The gitlab_release_index and gitlab_release_notes styles, and the .tmpl output templates. These are used only by the gitlab project.
• Local markdownlint overrides in cli (ol-prefix, commands-show-output) and in artifact-registry (proper-names, ignores).
• artifact-registry also keeps its own .vale/local style and .vale-user.ini.

Update checklist

1. gitlab-runner: sync docs/.vale/gitlab_base, docs/.vale/gitlab_docs, and docs/.markdownlint/rules/unnecessary_traversal.js: Sync Vale and markdownlint configuration from t... (gitlab-org/gitlab-runner!7208 - merged)
2. omnibus-gitlab: sync doc/.vale/gitlab_base, doc/.vale/gitlab_docs, and doc/.markdownlint/rules/unnecessary_traversal.js: Sync Vale and markdownlint configuration from t... (gitlab-org/omnibus-gitlab!9700 - merged)
3. charts/gitlab: sync doc/.vale/gitlab_base, doc/.vale/gitlab_docs, and doc/.markdownlint/rules/unnecessary_traversal.js: Sync Vale and markdownlint configuration from t... (gitlab-org/charts/gitlab!5275 - merged)
4. gitlab-operator: sync doc/.vale/gitlab_base, doc/.vale/gitlab_docs, and doc/.markdownlint/rules/unnecessary_traversal.js: Sync Vale and markdownlint configuration from t... (gitlab-org/cloud-native/gitlab-operator!1632 - merged)
5. cli: sync docs/.vale/gitlab_base and docs/.vale/gitlab_docs: chore(lint): sync Vale configuration from the g... (gitlab-org/cli!3747 - merged)
6. artifact-registry: sync .vale/gitlab_base: Draft: chore(lint): sync Vale configuration fro... (gitlab-org/ops/artifact-registry!1698 - closed)

Each merge request contains the configuration sync in one commit and any resulting documentation fixes in a second commit.

Issue close

Close this issue when all six merge requests are merged.