Vale

https://docs.vale.sh/
Admin
Vale is a command-line tool that brings code-like linting to prose, allowing developers and writers...
Tokens:99,291
Snippets:937
Trust Score:8.8
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Example .vale.ini configuration

Source: https://docs.vale.sh/topics/.vale.ini

A complete example configuration file showing global settings, a [formats] section mapping mdx to md, and glob sections for applying styles. The generator writes a starting file, and vale sync installs packages named by Packages.

```ini
StylesPath = styles
MinAlertLevel = suggestion
Packages = Microsoft

[formats]
mdx = md

[*]
BasedOnStyles = Vale

[*.{md,mdx}]
BasedOnStyles = Vale, Microsoft
Microsoft.Contractions = NO

```

--------------------------------

### Vale configuration with Packages list

Source: https://docs.vale.sh/keys/packages

Configuration file example showing how to list packages in the `Packages` key. `vale sync` installs each named package into the `StylesPath`. The `[*.md]` section applies the styles to Markdown files.

```ini
StylesPath = styles

Packages = Microsoft, write-good

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

--------------------------------

### Install typst2vast CLI

Source: https://docs.vale.sh/formats/typst

Install the typst2vast CLI, which is required for Vale to process Typst files. The executable must be available in your $PATH after installation.

```bash
$ cargo install typst2vast

```

--------------------------------

### pre-commit configuration for Vale with vale sync

Source: https://docs.vale.sh/integrations/pre-commit

Example pre-commit configuration that runs 'vale sync' before Vale. Pin 'rev' to a release tag rather than a commit to avoid stale installations and missing features.

```yaml
repos:
  - repo: https://github.com/vale-cli/vale
    rev: v3.24.0
    hooks:
      - id: vale
        name: vale sync
        pass_filenames: false
        args: [sync]
      - id: vale
        args: [--output=line, --minAlertLevel=error]
```

--------------------------------

### Install Vale with snap

Source: https://docs.vale.sh/topics/installation

Installs Vale using Snapcraft, which works across distributions.

```bash
$ sudo snap install vale
```

--------------------------------

### Install Vale with pkg on FreeBSD

Source: https://docs.vale.sh/topics/installation

Installs Vale on FreeBSD from the ports collection as textproc/vale.

```bash
$ pkg install vale
```

--------------------------------

### Install Vale with Scoop on Windows

Source: https://docs.vale.sh/topics/installation

Installs Vale on Windows using Scoop.

```powershell
> scoop install vale
```

--------------------------------

### Vale LSP initializationOptions configuration example

Source: https://docs.vale.sh/guides

Example of the initializationOptions object sent by a client when connecting to vale-ls. Shows the default settings for installVale, syncOnStartup, filter, and configPath.

```json
{
  "initializationOptions": {
    "installVale": true,
    "syncOnStartup": true,
    "filter": "",
    "configPath": ""
  }
}
```

--------------------------------

### Ignore files example

Source: https://docs.vale.sh/checks/spelling

Shows an example ignore file listing words to ignore and a configuration that references ignore files relative to the active ignore directory.

```text
destructuring
transpiler

```

```yaml
extends: spelling
message: "Did you really mean '%s'?"
level: error
ignore:
  - ignore1.txt
  - ignore2.txt

```

--------------------------------

### Install Vale with apt on Debian/Ubuntu

Source: https://docs.vale.sh/topics/installation

Installs Vale on Debian and Ubuntu after setting up the pkg.haus APT archive.

```bash
$ sudo apt install vale
```

--------------------------------

### Install Vale with pacman on Arch Linux

Source: https://docs.vale.sh/topics/installation

Installs Vale on Arch Linux from the official repositories.

```bash
$ sudo pacman -S vale
```

--------------------------------

### Install Vale with Chocolatey on Windows

Source: https://docs.vale.sh/topics/installation

Installs Vale on Windows using Chocolatey.

```powershell
> choco install vale
```

--------------------------------

### Install Vale from source using go install

Source: https://docs.vale.sh/topics/installation

Builds Vale for any platform Go supports. Requires Go 1.25.7 or later and a C compiler due to cgo. The resulting binary reports its version as 'master'.

```shell
$ go install github.com/vale-cli/vale/v3/cmd/vale@latest
```

--------------------------------

### Install Vale with npm

Source: https://docs.vale.sh/topics/installation

Installs Vale as a dev dependency via npm; run it with npx vale.

```bash
$ npm install --save-dev @vvago/vale
```

--------------------------------

### Vale CLI command examples

Source: https://docs.vale.sh/topics/cli

Shows example invocations for each Vale CLI command: sync, test, ls-config, ls-metrics, ls-dirs, ls-vars, and help. Each command is shown with its typical usage.

```shell
$ vale sync
```

```shell
$ vale test styles
```

```shell
$ vale ls-config
```

```shell
$ vale ls-metrics README.md
```

```shell
$ vale ls-dirs
```

```shell
$ vale ls-vars
```

```shell
$ vale help sync
```

--------------------------------

### Install Vale with pip

Source: https://docs.vale.sh/topics/installation

Installs Vale into the active Python environment via pip; pin it in requirements.txt or pyproject.toml.

```bash
$ pip install vale
```

--------------------------------

### Output of existence rule example

Source: https://docs.vale.sh/checks

Example output from the existence rule, showing the file, line, column, rule name, and message for each match.

```text
test.md:1:9:style.Hedging:Consider removing 'arguably'
test.md:1:42:style.Hedging:Consider removing 'appears to be'

```

--------------------------------

### Vale --output=line example

Source: https://docs.vale.sh/topics/cli

Use the --output=line flag to get one alert per line, formatted for editors and scripts. The output shows the file, line, column, rule, and message for each alert.

```bash
$ vale --output=line README.md
README.md:3:17:write-good.Weasel:'very' is a weasel word!
README.md:3:37:write-good.Passive:'were fixed' may be passive voice. Use active voice if you can.
README.md:6:23:Vale.Spelling:Did you really mean 'detials'?
```

--------------------------------

### message format specifier example

Source: https://docs.vale.sh/checks/occurrence

Example of the `message` key using a format specifier `%s` that is populated with the number of occurrences.

```yaml
message: 'Titles should use fewer than 70 characters (found: %s).'

```

--------------------------------

### Check Vale version

Source: https://docs.vale.sh/topics/quickstart

Check that Vale is installed and see its version. Run after installing via a package manager such as brew or choco.

```bash
$ vale --version
```

--------------------------------

### Install Vale with winget on Windows

Source: https://docs.vale.sh/topics/installation

Installs Vale on Windows using winget with the exact package ID errata-ai.Vale.

```powershell
> winget install -e --id errata-ai.Vale
```

--------------------------------

### suggest

Source: https://docs.vale.sh/fixes

Documentation for the suggest function, including its signature, parameters, return type, and usage examples for both the spellings parameter and custom Tengo scripts.

```APIDOC
## suggest

### Description
Computes a rule's suggestions.

### Function Signature
```
func suggest(match string) []string
```

### Parameters
- **match** (string) - The matched text.

### Returns
- **[]string** - A list of suggested replacements.

### Usage

#### `spellings`

```yaml
action:
  name: suggest
  params:
    - spellings
```

Returns the closest words to the match, up to six, by Levenshtein distance. Candidates include every dictionary the rule loads, words in its ignore files, and terms in the configuration's vocabularies. A project's own word comes first among ties, and a capitalized match gets capitalized suggestions. These suggestions are not computed during linting; the alert's `Suggestions` field is left empty and an editor requests them per alert. On a rule that extends `spelling`, a bare `name: suggest` means the same thing.

#### A script

```yaml
action:
  name: suggest
  params:
    - CamelToSnake.tengo
```

Any other parameter names a Tengo script. Vale looks for it in `<StylesPath>/config/actions` first, then in the rule's own style directory. A script that is in neither place is a load-time error.

The script receives the matched text as `match` and must leave its answer in `suggestions`, an array of strings; anything in the array that is not a string is dropped. The `text`, `fmt`, and `math` modules are available to import.

Example script (`CamelToSnake.tengo`):

```tengo
text := import("text")

// `match` is the rule's matched text.
made := text.re_replace(`([A-Z]\w+)([A-Z]\w+)`, match, `$1-$2`)

made = text.replace(made, "-", "_", 1)
made = text.to_lower(made)

// `suggestions` is what Vale reads back.
suggestions := [made]
```

Example rule using the script:

```yaml
extends: existence
message: "'%s' should be in snake_case."
nonword: true
level: error
action:
  name: suggest
  params:
    - CamelToSnake.tengo
tokens:
  - '[A-Z]\w+[A-Z]\w+'
```

A script is compiled once per run and executed for each match.
```

--------------------------------

### Install docutils for reStructuredText support

Source: https://docs.vale.sh/formats/restructuredtext

Install the docutils package, which provides the rst2html script that Vale uses to parse reStructuredText files.

```bash
$ pip install docutils
```

--------------------------------

### Example directory structure

Source: https://docs.vale.sh/guides/globbing

A sample directory structure used to illustrate how glob patterns match files. The `cases/test/` directory contains `a.md`, `b/b.md`, and `c.md`.

```text
cases/test/
├── a.md
├── b
│   └── b.md
└── c.md
```

--------------------------------

### tokens key example

Source: https://docs.vale.sh/checks

Example of the tokens key, which is a list of strings or regular expressions that are transformed into a word-bounded, non-capturing group.

```yaml
tokens:
  - appears to be
  - arguably

```

--------------------------------

### Configure StylesPath in .vale.ini

Source: https://docs.vale.sh/keys/stylespath

Example of setting the StylesPath relative to the .vale.ini file and using a style from that directory.

```ini
# .vale.ini
# ci/
# └── vale/
#     └── styles/
StylesPath = ci/vale/styles

[*.md]
# House is a directory in ci/vale/styles.
BasedOnStyles = House
```

--------------------------------

### Sample output for min rule

Source: https://docs.vale.sh/checks/occurrence

Example output from Vale when the `min` rule is violated, showing the file, line, column, rule name, and message.

```text
test.md:3:1:style.Examples:A paragraph here has no example (found 0).

```

--------------------------------

### raw key example

Source: https://docs.vale.sh/checks

Example of using the raw key for more control over the regular expression, allowing complex patterns without post-processing. Each entry is concatenated with the previous one.

```yaml
extends: existence
message: "Incorrect use of symbols in '%s'."
ignorecase: true
raw:
  - $[d]* ?(?:dollars|usd|us dollars)

```

--------------------------------

### Install and configure the Commits package

Source: https://docs.vale.sh/guides/commit-messages

Add the Commits package to your Vale configuration and sync it. The package requires Vale v3.21.0 or later.

```ini
StylesPath = styles
Packages = Commits

[COMMIT_EDITMSG]
BasedOnStyles = Commits, Conventional
```

```shell
$ vale sync
```

--------------------------------

### CLI output for capture group substitution

Source: https://docs.vale.sh/checks/substitution

CLI output for the capture group substitution example, showing the suggested replacement for the matched phrase.

```text
test.md:1:13:style.Paths:Consider using 'in the config directory' instead of 'within the config directory'
```

--------------------------------

### Ship vocabularies in a package with .vale.ini

Source: https://docs.vale.sh/guides/faq

Example .vale.ini for shipping vocabularies in a package. Vocab is a global setting and the vocabulary rules require the Vale style to be enabled.

```ini
StylesPath = vale/styles
MinAlertLevel = suggestion

Packages = https://github.com/spectrocloud/spectro-vale-pkg/releases/latest/download/spectrocloud-docs-internal.zip

# `Vocab` is a global setting
Vocab = spectrocloud-vocab

[*.md]
# The vocab rules, `Vale.Avoid` and `Vale.Terms`, require the `Vale` style to be enabled.
BasedOnStyles = Vale, spectrocloud-docs-internal

```

--------------------------------

### Conditional section header examples

Source: https://docs.vale.sh/topics/.vale.ini

Examples of conditional section headers. The expression is written like a filter, with capitalized fields starting with a dot. A field a file doesn't have is nil.

```ini
[*.md if .Meta.published == false or .Meta.draft]
[*.md if "internal" in .Meta.tags]
[*.md if .Name startsWith "_"]
[docs/*.md if .Path startsWith "docs/archive/" and .Meta.layout != "page"]
```

--------------------------------

### trim_left action: remove leading characters

Source: https://docs.vale.sh/fixes/edit

Removes any of the given characters from the start of the match. The example trims leading spaces after sentence punctuation.

```yaml
extends: existence
message: "'%s' too many spaces."
level: warning
nonword: true
action:
  name: edit
  params:
    - trim_left
    - ' '
tokens:
  - '(?<=[a-z][.!?] ) [A-Z]'
```

--------------------------------

### Show help with --help

Source: https://docs.vale.sh/topics/cli

Use the --help option to print the listing of options and commands; after a command, that command's help.

```bash
$ vale sync --help
```

--------------------------------

### Vale --output=json example

Source: https://docs.vale.sh/topics/cli

Use the --output=json flag to get alerts as a JSON object keyed by file path. Each alert includes the rule, level, matched text, line and span, message, and any action with its resolution.

```json
{
	"README.md": [
		{
			"Action": { "Name": "replace", "Params": ["use"] },
			"Suggestions": ["use"],
			"Span": [9, 15],
			"Check": "House.Terms",
			"Description": "",
			"Link": "",
			"Message": "Use 'use' instead of 'utilize'.",
			"Severity": "error",
			"Match": "utilize",
			"Line": 1
		}
	]
}
```

--------------------------------

### Apply multiple sections to a file

Source: https://docs.vale.sh/topics/.vale.ini

Shows a file matching multiple sections. guide.fr.md matches both globs and takes the first section's settings then the second's. When both sections set the same key, the later one holds for that file.

```ini
[*.md]
BasedOnStyles = Google

[*.fr.md]
Google.Spelling = NO
Google.Exclamation = NO
```

--------------------------------

### Apply styles to all files

Source: https://docs.vale.sh/keys/basedonstyles

Use the catch-all section to apply styles to every file.

```ini
[*]
BasedOnStyles = Vale
```

--------------------------------

### Match a word only when it starts a sentence

Source: https://docs.vale.sh/guides/faq

Combine a scope with a lookbehind to match a word only when it starts a sentence.

```yaml
extends: existence
message: "'%s' should only be capitalized when starting a sentence."
level: error
nonword: true
scope:
  - heading
  - list
  - sentence
tokens:
  - (?<=\s)Internet(?! Service Provider| Protocol)
```

--------------------------------

### Install Vale with conda

Source: https://docs.vale.sh/topics/installation

Installs Vale from conda-forge into the active conda environment, or list it under dependencies in environment.yml.

```bash
$ conda install conda-forge::vale
```

--------------------------------

### Sync styles with vale sync

Source: https://docs.vale.sh/topics/quickstart

Download the styles named in Packages. Run again whenever you change Packages. The output confirms the sync succeeded.

```bash
$ vale sync
```

```text
 SUCCESS  Synced 1 package(s) to 'styles'.
```

--------------------------------

### convert action configuration with simple parameter

Source: https://docs.vale.sh/fixes/convert

Example configuration for the convert action using the 'simple' parameter to convert matched text to lower case with words separated by single spaces.

```yaml
extends: existence
message: "'%s' should be '%s'."
action:
  name: convert
  params:
    - simple
tokens:
  - '[A-Z]{2,}(?: [A-Z]{2,})+'
```

--------------------------------

### Install Vale with Homebrew on macOS

Source: https://docs.vale.sh/topics/installation

Installs Vale on macOS using Homebrew, which tracks new releases closely.

```bash
$ brew install vale
```

--------------------------------

### vale input examples

Source: https://docs.vale.sh/topics/cli

Shows the three ways to pass input to the vale command: named files and directories (recursively), standard input with the --ext flag, and a plain string that is not a path. A directory is walked for every file its configuration has a section for, narrowed by --glob when given. Input on stdin is read as plain text unless --ext names a format or --path names the file it came from.

```bash
vale README.md docs/          # named files and directories, recursively
cat draft.md | vale --ext=.md # standard input
vale "Some text to check."    # a string that is not a path
```

--------------------------------

### Configure shared styles with vale sync

Source: https://docs.vale.sh/keys

Shows how to set up a shared style location for multiple projects. The first block configures the default configuration file to install shared packages, the second runs vale sync with that configuration, and the third shows a project configuration that references both shared and project-specific styles.

```ini
# ~/Library/Application Support/vale/.vale.ini
Packages = Microsoft, write-good
```

```bash
$ vale sync --config "$HOME/Library/Application Support/vale/.vale.ini"
```

```ini
# .vale.ini
StylesPath = styles

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

--------------------------------

### Example input for script rule

Source: https://docs.vale.sh/checks/script

Example input for the script rule: a section with five one-line paragraphs. The script flags the fourth paragraph.

```markdown
# Intro

One.

Two.

Three.

Four.

Five.

# Next

Six.
```

--------------------------------

### Sync shared packages into the default location

Source: https://docs.vale.sh/keys/stylespath

Shows how to sync Vale packages into the default location using a configuration file that lives there. The first block is the configuration file content, and the second is the command to run. This setup lets a machine keep one copy of shared styles for every project.

```ini
# ~/Library/Application Support/vale/.vale.ini
Packages = Microsoft, write-good

```

```bash
$ vale sync --config "$HOME/Library/Application Support/vale/.vale.ini"

```

--------------------------------

### Markdown example with inline code

Source: https://docs.vale.sh/keys/ignoredscopes

Example Markdown content demonstrating that Vale will not raise alerts for content within backticks when IgnoredScopes includes code.

```markdown
This is a sentence that contains inline `code`.
```

--------------------------------

### Package .vale.ini with StylesPath and Packages

Source: https://docs.vale.sh/keys/packages

Example .vale.ini for a package that includes both a configuration and a styles directory. It sets StylesPath to styles, lists additional packages, and enables the MyStyle rules for Markdown and AsciiDoc files.

```ini
# MyPackage/.vale.ini
StylesPath = styles

Packages = proselint

[*.{md,adoc}]
BasedOnStyles = MyStyle
```

--------------------------------

### Specify configuration file with --config

Source: https://docs.vale.sh/topics/cli

Use the --config option to specify a configuration file instead of searching for one.

```bash
$ vale --config='path/to/.vale.ini' README.md
```

--------------------------------

### Folder structure for vocabularies

Source: https://docs.vale.sh/keys/vocabularies

Shows the directory layout for a `StylesPath` containing two styles (`MyStyle`, `MyOtherStyle`) and two vocabularies (`Blog`, `Marketing`). Each vocabulary folder contains `accept.txt` and `reject.txt` files.

```text
$ tree styles
├───MyStyle
├───config
│   └───vocabularies
│       ├───Blog
│       │   ├───accept.txt
│       │   └───reject.txt
│       └───Marketing
│           ├───accept.txt
│           └───reject.txt
└───MyOtherStyle
```

--------------------------------

### Example output for repetition rule

Source: https://docs.vale.sh/checks/repetition

Expected output from the repetition rule when applied to the example text. It shows two matches for repeated words 'is' and 'the'.

```text
test.md:1:6:style.Repetition:'is' is repeated!
test.md:1:22:style.Repetition:'the' is repeated!
```

--------------------------------

### Package meta.json manifest with releases

Source: https://docs.vale.sh/keys/packages

Example of a package's meta.json manifest that lists releases with their required Vale versions and archive URLs. Sync uses this to find a compatible release when the running Vale is older than the latest package requires.

```json
{
  "vale_version": ">=3.23.0",
  "releases": [
    {"version": "v0.3.0", "vale_version": ">=3.23.0", "url": "https://example.com/readability/v0.3.0/Readability.zip"},
    {"version": "v0.2.0", "vale_version": ">=2.13.0", "url": "https://example.com/readability/v0.2.0/Readability.zip"}
  ]
}
```

--------------------------------

### Example text with repeated word across markup

Source: https://docs.vale.sh/checks/repetition

Example sentence demonstrating that the built-in Vale.Repetition rule catches repeated words even across markup boundaries, such as a link.

```markdown
See the Mermaid [Mermaid user guide][1].
```

--------------------------------

### vale sync --plain-progress output

Source: https://docs.vale.sh/keys/packages

Command and output showing `vale sync --plain-progress` syncing the packages listed in the configuration. The output prints one line per package and a success message with the target `StylesPath`.

```shell
$ vale sync --plain-progress
Synced Microsoft
Synced write-good
 SUCCESS  Synced 2 package(s) to '/home/me/docs/styles'.
```

--------------------------------

### Install Vale Claude Code plugin

Source: https://docs.vale.sh/guides/agents

Commands to add the Vale agent-tools marketplace and install the plugin in Claude Code. The plugin includes skills, an edit-time hook, and the Vale CMS MCP server.

```shell
/plugin marketplace add vale-cli/agent-tools
/plugin install vale@agent-tools
```

--------------------------------

### Example .vale.ini configuration

Source: https://docs.vale.sh/guides/globbing

A sample `.vale.ini` file that applies the `Test` style to Markdown files. Used to demonstrate how glob patterns in the configuration interact with the `--glob` flag.

```ini
StylesPath = styles

[*.md]
BasedOnStyles = Test
```

--------------------------------

### Renovate configuration to enable pre-commit manager

Source: https://docs.vale.sh/topics/installation

Minimal renovate.json that enables the pre-commit manager, which is off by default. Extends the recommended config and the :enablePreCommit preset.

```json
{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended", ":enablePreCommit"]
}
```

--------------------------------

### Skip global configuration with --no-global

Source: https://docs.vale.sh/topics/cli

Use the --no-global option to skip reading the user-level configuration.

```bash
$ vale --no-global README.md
```

--------------------------------

### Vale message with two placeholders

Source: https://docs.vale.sh/topics/actions

A message template with two placeholders: the first gets the match, the second gets the fix. If the action yields several suggestions, they are joined (e.g., 'colour' should be 'color or colors'). With no action, the second placeholder stays empty.

```yaml
message: "'%s' should be '%s'."

```

--------------------------------

### Markdown link example

Source: https://docs.vale.sh/topics/urls

In Markdown, the link text is linted and the URL is not.

```markdown
[our page on Ruby](https://example.com/ruby)
```

--------------------------------

### Example text for exceptions and vocabulary

Source: https://docs.vale.sh/checks/conditional

Sample text demonstrating the exceptions and vocabulary rule. It includes accepted terms (API, AWS CLI) and an undefined acronym (AWS alone) to show how the rule flags undefined uses.

```text
The API is fine. The AWS CLI is fine. AWS alone is not.
```

--------------------------------

### Basic substitution rule with swap map and CLI output

Source: https://docs.vale.sh/checks/substitution

A complete substitution rule configuration with a swap map and the corresponding Vale CLI output. The rule warns when 'abundance' or 'accelerate' is used, suggesting 'plenty' or 'speed up' respectively. The output shows the file, line, column, rule name, and message for each match.

```yaml
extends: substitution
message: Consider using '%s' instead of '%s'
level: warning
ignorecase: false
# swap maps tokens in form of bad: good
swap:
  abundance: plenty
  accelerate: speed up
```

```text
test.md:1:13:style.Preferred:Consider using 'plenty' instead of 'abundance'
test.md:1:34:style.Preferred:Consider using 'speed up' instead of 'accelerate'
```

--------------------------------

### Example heading triggering capitalization rule

Source: https://docs.vale.sh/checks/capitalization

A sample heading that would be checked by the capitalization rule.

```markdown
## Getting started with the API

```

--------------------------------

### trim action: remove from both ends

Source: https://docs.vale.sh/fixes/edit

Removes any of the given characters from both ends of the match. The example trims asterisks and underscores.

```yaml
action:
  name: edit
  params:
    - trim
    - '*_'
```
Tokens:
Raw