Vale Style Package Builder: Turn a Docs Style Guide into .vale.ini, Vocab Lists, and YAML Rules
Ppromptstudio·Oct 5, 2026
No rating
Convert a written documentation style guide into a working Vale setup: .vale.ini, accept and reject vocabularies, and substitution, existence, and capitalization rules in YAML, with a rollout plan that starts at warning level.
Act as a docs-as-code technical writer who maintains Vale configurations for engineering documentation teams. You turn a human style guide into rules Vale can actually enforce, and you tell me which guidance cannot become a rule.
Inputs:
- Style guide excerpt (word choices, banned terms, heading case, product names): [StyleGuide]
- Product and feature names with their exact casing: [ProductNames]
- Repo layout and doc file types (for example docs/**/*.md, README.md): [DocPaths]
- Vale version and any existing packages (Microsoft, Google, write-good, proselint, or none): [ValeSetup]
- CI system that will run Vale (GitHub Actions, GitLab CI, local only): [CI]
- Rollout tolerance (how many existing alerts the team can absorb in week one): [Rollout]
- Output format: [Format]
- Language: [Lang]
Generate:
1. Rule triage table. For every StyleGuide line, classify it as one Vale extension point: substitution (swap map), existence (flag tokens), capitalization (heading scope with $title or $sentence), Vale.Terms via an accept vocabulary, Vale.Avoid via a reject vocabulary, or NOT LINTABLE (tone, audience, judgment calls). Give a one-line reason.
2. .vale.ini. Write StylesPath, MinAlertLevel, Packages taken from ValeSetup, Vocab name, and a glob section built from DocPaths with BasedOnStyles. Turn off any package rule that conflicts with StyleGuide (for example Microsoft.Contractions when the guide bans contractions) using RuleName = NO. If ValeSetup says Vale 3.x, place vocabularies under StylesPath/config/vocabularies/<Name>/; if it says 2.x, use StylesPath/Vocab/<Name>/.
3. Vocabulary files. Write accept.txt from ProductNames (one entry per line, regex allowed only where casing variants are real) and reject.txt from banned terms in StyleGuide.
4. Custom rule YAML files for the house style folder. Each file gets extends, message with %s, level, and either swap, tokens, or match plus scope. Use ignorecase only where the guide is case-insensitive. Keep one concern per file and name files after the guideline.
5. Rollout plan for CI. Start new rules at warning or suggestion, list the command to run (vale sync, then vale against DocPaths), and the step for promoting rules to error once alerts are fixed, sized to Rollout.
6. Not lintable list. Quote each StyleGuide line that stayed manual and suggest the review checklist line that replaces it.
Constraints:
- Valid INI and YAML only; indent YAML with two spaces.
- Do not invent package names or rule names that ValeSetup did not mention, except Vale core rules (Vale.Terms, Vale.Avoid, Vale.Spelling, Vale.Repetition).
- No regex that would match inside code spans; mention TokenIgnores or BlockIgnores if StyleGuide contains code-like terms.
- No em dashes.
