How to Use the Vale Style Package Builder Prompt to Lint a Docs Style Guide

Most documentation teams have a style guide. Far fewer have one that is enforced. The guide lives in a wiki page, new contributors skim it once, and reviewers end up leaving the same comment about "log in" versus "sign in" on every pull request. Vale fixes that by linting prose the way ESLint lints code, but only if someone translates the guide into Vale's configuration format. That translation is the slow part, and it is exactly what the Vale Style Package Builder: Turn a Docs Style Guide into .vale.ini, Vocab Lists, and YAML Rules prompt is built for.

Why style guides are hard to lint

A style guide mixes three kinds of guidance. Some lines are mechanical swaps, like "write email, not e-mail." Some are word bans, like "avoid simply and just." And some are judgment calls, like "address the reader directly" or "prefer active voice." Vale is excellent at the first two and can only approximate the third. Teams that try to lint everything end up with noisy rules that people learn to ignore.

The prompt starts with a triage table for that reason. Every line from your guide is assigned to one Vale mechanism or marked NOT LINTABLE, with a one-line reason. That table alone is worth having, because it shows the team which rules a machine will enforce and which still belong to human review.

What the prompt builds

After triage, the prompt writes the actual files:

• A .vale.ini with StylesPath, MinAlertLevel, Packages, a Vocab name, and a glob section for your doc paths with BasedOnStyles.
• Vocabulary files. In Vale 3.x these live under styles/config/vocabularies/<Name>/ as accept.txt and reject.txt. Product names go in accept, which lets the core Vale.Terms rule enforce exact casing. Banned terms go in reject for Vale.Avoid. If you are still on Vale 2.x, the prompt uses the older Vocab folder instead.
• One YAML rule per guideline. Swaps use extends: substitution with a swap map. Word bans use extends: existence with tokens. Heading case uses extends: capitalization with scope: heading and match: $sentence or $title.

It also handles conflicts with packages you already use. If you synced the Microsoft package and your guide has its own heading rule, the prompt turns off the package version with RuleName = NO so writers do not get two alerts for one problem.

How to fill the inputs

Paste the real style guide lines into StyleGuide, not a summary. The more literal the wording, the better the triage. Put product and feature names with exact casing into ProductNames, since these become your accept vocabulary. In DocPaths, describe where docs live and what file types you lint, for example docs/**/*.md plus a root README.

ValeSetup matters more than it looks. Tell the prompt your Vale major version and which packages are already synced, because vocabulary paths changed between versions and package rule names differ. CI tells it whether to write the rollout around GitHub Actions, GitLab CI, or local runs. Rollout is your tolerance for noise in week one, which shapes how many rules start at warning versus error.

Reading the output

The example run converts a short guide for a fictional product into four custom rules, two vocabulary files, and a three-week rollout. A few details are worth noticing:

• "Login" is only banned as a verb, so the prompt deliberately does not swap the noun. A blind swap would also rewrite "the login page." It tells you that case stays with reviewers until you write a more specific rule.
• Contractions are allowed by the guide, and the Microsoft package already nudges writers toward contractions, so the prompt keeps that rule at suggestion rather than turning it off.
• Code spans and fenced blocks in Markdown are skipped by Vale by default, so a CLI name inside backticks is never flagged.

The rollout plan starts everything at warning or suggestion, so pull requests get annotations but are not blocked. Mechanical rules are promoted to error first, once the existing hits are fixed. Heuristic rules such as passive voice stay low.

Common mistakes to avoid

• Turning every guideline into an error on day one. Writers will disable Vale rather than fix hundreds of legacy alerts.
• Using ignorecase: true everywhere. If your guide is case-sensitive for a term, the rule should be too.
• Writing one giant rule file. One concern per file makes it easy to promote, demote, or delete a single rule.
• Forgetting the "not lintable" list. Those lines should become a short review checklist so they do not disappear once linting starts.

When to use it

Use this prompt when you are introducing Vale to an existing docs repo, when you are migrating a team from a wiki style guide to docs-as-code, or when an inherited Vale setup has drifted away from the written guide. It is not a substitute for the guide itself, and it will not invent rules your guide does not contain.

Related PromptDig links

• Prompt: Vale Style Package Builder: Turn a Docs Style Guide into .vale.ini, Vocab Lists, and YAML Rules
• Find more writing and docs prompts: Browse more prompts
• Built a better Vale workflow? Share a prompt