mirror of
https://github.com/docker/docs.git
synced 2026-06-19 07:35:16 +00:00
David Karlsson
f6f287b6d4
The vale ruleset was producing ~1,600 violations, a meaningful fraction
of which were noise from a hard-to-maintain vocabulary file, sprawling
shortcode-ignore regex, and rule patterns with known false positive
modes. This commit cleans up all three.
Vocabulary fixes (accept.txt):
- Fix the case-insensitive catch-all `(?i)[A-Z]{2,}'?s` which was
matching every plural word and suppressing other rule checks on them
- Fix wrong-cased canonical entries that caused cascading Vale.Terms
false positives: Duckduckgo→DuckDuckGo, fluentd→Fluentd, [Rr]eadme
removed (README is correct), VPNKit, AppArmor, OpenSSL, etc.
- Remove `Mac` (Apple brand) — conflicted with `MAC` (address) under
Vale's case-insensitive vocab matching; both are in the base dictionary
- Resolve duplicate case entries (uncaptured/Uncaptured, etc.) by using
narrow character-class regex like `[Uu]ncaptured` to opt out of Terms
enforcement
- Add common tech terms missing from the vocab (Vitest, Deno, Pinecone,
Wolfi, Streamlit, ESLint, Kustomize, HAProxy, Qdrant, etc.)
- Add common acronyms and abbreviations as canonical uppercase (URL,
JSON, TCP, UID, SHA, CMD, VM, GPG, KVM)
Rule fixes:
- TokenIgnores/BlockIgnores collapsed from 7 patterns to 2 (one for
inline shortcodes, one for multi-line block shortcodes)
- Docker.Capitalization regex tightened to skip `docker` preceded or
followed by `-`/`.` (image names, URLs) and word chars after
(`dockerd`, `Dockerfile`)
- Docker.RecommendedWords `vs: versus` now excludes "VS Code" and "vs."
(heading abbreviation)
- Docker.We becomes case-sensitive so `US` (country) isn't flagged as
the pronoun `us`
- Docker.VersionText requires X.Y minimum to avoid matching port numbers
like "1025 or higher"
- Docker.Units drops KB→kB swap (KB is conventional in user-facing docs)
Section overrides:
- Brace-expansion glob `[{a,b,c}]` consolidates repeated path lists
- Release notes and previous-versions content fully disabled (each rule
listed explicitly because Vale's BasedOnStyles= empty in a section
doesn't actually disable rules, despite the docs)
- Reference content disables Vale.Spelling/Vale.Terms/Docker.Capitalization
Net result: 1,429 → ~1,070 violations, with spot-checks confirming the
remaining violations are real (CLI commands without backticks, first-
person plurals, `allows`→`lets`, etc.) and not artifacts of the rules.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>