mirror of
https://github.com/docker/docs.git
synced 2026-06-19 07:35:16 +00:00
vale: overhaul ruleset and clean up vocab
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>
This commit is contained in:
@@ -80,6 +80,25 @@ introduced, which is permanently true.
|
||||
|
||||
- Use lowercase "config" in prose — `vale.Terms` flags a capital-C "Config"
|
||||
|
||||
### Updating the vocabulary
|
||||
|
||||
If Vale flags a legitimate tech term, product name, or compound identifier
|
||||
as a misspelling, add it to `_vale/config/vocabularies/Docker/accept.txt`.
|
||||
This is optional — only update when a real new term is missing, not to
|
||||
silence individual violations.
|
||||
|
||||
- Use the canonical form for case-sensitive product names (`PyTorch`,
|
||||
`GitHub`, `Kubernetes`, `BuildKit`). `Vale.Terms` enforces that exact
|
||||
case across the docs.
|
||||
- Use `[Aa]bcd` character-class regex for words that legitimately appear
|
||||
in multiple cases (e.g., sentence-starting capitalization, or a name
|
||||
that's also a generic noun). This covers spelling without enforcing
|
||||
a single canonical form.
|
||||
- Avoid broad regex patterns — entries that match many words at once
|
||||
(especially with `(?i)`) suppress other rule checks on every match.
|
||||
- Don't add a wrong-cased entry to silence one false positive — it
|
||||
cascades into `Vale.Terms` violations on every correct usage.
|
||||
|
||||
## Alpine.js patterns
|
||||
|
||||
Do not combine Alpine's `x-show` with the HTML `hidden` attribute on the
|
||||
|
||||
Reference in New Issue
Block a user