Vale Integration

Vale is an open-source prose linter that enforces style rules across documentation. When Vale is configured for a doc collection, Promptless lints prose before creating suggestions, catching style violations before they reach your review queue.

What Promptless does

When Vale is enabled, Promptless:

• Syncs external style packages referenced in your Vale config once per session
• Lints every prose file it creates or substantially edits
• Treats error-severity violations as blocking and fixes them before creating the suggestion
• Weighs warning and suggestion-severity results against your established style before acting

This keeps suggestions aligned with your style guide from the start, reducing back-and-forth during review.

Setup

Vale is enabled automatically when Promptless detects a Vale configuration file in your docs repository.

Automatic detection

During doc collection setup, Promptless scans your repository for .vale.ini or vale.ini. If found, Vale linting activates automatically using that config file’s location.

Manual configuration

You can also set the Vale config path manually:

1. Open the Promptless dashboard.
2. Go to your doc collection.
3. Click the edit button.
4. Under Vale config, enter the repo-relative path to your Vale configuration file (e.g., .vale.ini or docs/.vale.ini).

If your Vale config references external style packages (like Microsoft, Google, or write-good), Promptless downloads them automatically the first time it lints during a session.

How it works

Promptless runs Vale after drafting prose content:

1. Sync packages - Downloads any external style packages your config references (runs once per session)
2. Lint prose - Runs Vale on created or edited prose files
3. Evaluate results - Parses Vale’s output and categorizes violations by severity
4. Fix or flag - Automatically fixes error-severity violations; evaluates warnings and suggestions against your docs style

Vale only runs on prose content. Code blocks, commands, configuration, frontmatter, schemas, and tables are excluded from linting.

Severity handling

Vale classifies violations into three severity levels:

Severity	Behavior
error	Blocking. Promptless fixes these before creating the suggestion.
warning	Advisory. Promptless evaluates against your existing style and fixes when appropriate.
suggestion	Advisory. Promptless considers these but may preserve intentional style choices.

Error-severity rules are hard constraints. Warning and suggestion rules are guidance that Promptless balances against the established voice and conventions in your docs.

CI integration

Vale errors that slip through or arise from later edits are caught by Promptless’s automated CI handling. When Vale fails in a GitHub Actions workflow on a Promptless PR, Promptless analyzes the failure and pushes fixes to the branch automatically.

This works alongside other CI checks like broken link detection and Doc Detective tests, giving you layered quality gates without manual triage.

Creating a Vale config

If you don’t have a Vale configuration yet, create a .vale.ini file in your docs repository root:

StylesPath = .vale/styles
MinAlertLevel = warning

[*.md]
BasedOnStyles = Vale

This minimal config enables Vale’s built-in rules. For more comprehensive style enforcement, add external packages:

StylesPath = .vale/styles
MinAlertLevel = warning

Packages = Microsoft, write-good

[*.md]
BasedOnStyles = Vale, Microsoft, write-good

See the Vale documentation for detailed configuration options and available style packages.