Vale Documentation

Vale is a fast, cross-platform (Windows, macOS, and Linux) command-line tool designed to bring code-like linting to prose. It allows users to enforce specific style guides through a highly customizable extension system using YAML.

Key capabilities include:

• Markup Support: Understands formats like Markdown, AsciiDoc, reStructuredText, HTML, and XML to avoid false positives and intelligently exclude code snippets from prose rules.
• Extensibility: Supports custom rules and editorial style guides via YAML.
• Standalone: Distributed as standalone binaries that do not require external runtimes like Python or Node.js.

The Vale CLI can be used to lint specific files, entire directories, or text provided via standard input or as a string argument.

Linting Files or Directories

You can pass one or more files or directories as arguments to the command.

Linting via Standard Input (Stdin)

You can pipe text into Vale using the standard input stream.

Linting a String Argument

If you provide a single argument that does not exist as a file or directory, Vale treats it as a string to be linted.

Summary of Usage Patterns

# Lint specific files or directories
vale file1.md dir1/

# Lint via stdin
cat file.md | vale

# Lint a literal string
vale "this is some text to lint"

Vale is a syntax-aware command-line linter for prose that supports Markdown, AsciiDoc, reStructuredText, HTML, and more.

To use Vale, you need a configuration file (typically .vale.ini).

Basic Usage Patterns:

• Lint specific files: vale myfile.md myfile1.md mydir1
• Lint with a specific output format: vale --output=JSON [input...]
• General syntax: vale [options] [input...]

# Example .vale.ini configuration
MinAlertLevel = suggestion

[*]
	BasedOnStyles = Vale

To see a full listing of all available CLI options, commands, and flags, use the --help flag.

vale --help

Vale provides high-level understanding of several markup formats, allowing it to perform context-aware linting (e.g., ignoring code blocks during spell checks). Supported formats include:

• Markdown
• AsciiDoc
• reStructuredText
• HTML
• XML
• Org

Vale supports different output styles for error reporting. When using the CLI, you can specify how errors are displayed via the style parameter (typically controlled by a CLI flag in the main entrypoint).

Supported styles:

• JSON: Outputs the error details as a JSON object. If the error cannot be parsed into a standard Vale error format, it returns a fallback JSON object with code E100.
• line: Outputs a single-line string in the format path:line:code:text. This is useful for integration with text editors and IDEs.
• default: Falls back to the standard error string provided by the error object.

When the JSON style is selected, Vale outputs a JSON object containing the following fields:

• Line: The line number where the error occurred.
• Path: The file path to the file containing the error.
• Text: The descriptive text of the error.
• Code: The specific Vale rule code (e.g., E100 for unparseable errors).
• Span: The character position/span of the error.

When running Vale, verbose alerts provide a detailed breakdown of linting issues. The output includes:

• File Path: The path to the file being linted.
• Location: The line and column number (line:column).
• Severity Level: Color-coded indicators for error (red), warning (yellow), and suggestion (blue).
• Message: The description of the style violation.
• Check: The name of the specific rule/check that was triggered.

If the wrap option is disabled, the table output will not wrap text. The summary at the end of the output indicates the total count of errors, warnings, and suggestions found across all files or stdin.

The Vale CLI uses the following exit codes to indicate the result of the linting process:

• 0: Success. No issues were found, or the command completed successfully (e.g., --version).
• 1: Linting errors found. One or more style violations were detected (unless --no-exit is used).
• 2: Error. An internal error occurred during execution (e.g., configuration error, file not found).