DOCSEARCHbyAlgolia
Submit Docs

Vale Prose Linter

repository·v3·Indexed 11 days ago

https://github.com/errata-ai/vale

A high-performance, cross-platform command-line linter for prose that enforces style guides and spelling rules. It supports multiple markup formats including Markdown, AsciiDoc, reStructuredText, HTML, XML, and Org. Vale is highly customizable via a YAML-based extension system and provides flexible output formats such as JSON, CLI, and custom Go text/template outputs.

Tokens
5.4K
Snippets
24
Records
29
Agent score
91%

What's inside Vale

  1. What is Vale?

    v3

    Vale is a fast, cross-platform (Windows, macOS, and Linux) command-line tool designed to bring code-like linting to prose. It allows you to enforce specific editorial style guides or custom in-house rules.

    Key capabilities include:

    • Markup Support: Understands formats like Markdown, AsciiDoc, reStructuredText, HTML, XML, and Org to avoid syntax-related false positives and intelligently exclude code snippets from prose rules.
    • Extensibility: Highly customizable via a YAML-based extension system.
    • Standalone: Distributed as easy-to-install binaries that do not require external runtimes like Python or Node.js.

  2. Compare Vale with other prose linters

    v3

    Vale is a Go-based, MIT-licensed tool that supports spelling and style checks across multiple markup formats (Markdown, AsciiDoc, reStructuredText, HTML, XML, Org).

    Compared to other common tools:

    • textlint: JavaScript-based, supports similar markup but uses JavaScript for extensions.
    • RedPen: Java-based, supports a wider range of formats including Textile and LaTeX.
    • write-good / proselint / Joblint / alex: Generally more limited in markup support or extensibility compared to Vale.

  3. Use custom templates for Vale output

    v3

    Vale allows you to format linting results using user-defined templates. When using custom output, Vale processes the linted files and exposes the data to a Go text/template engine. The template engine is augmented with sprig functions to provide advanced text manipulation capabilities.

    To use a custom template, you must provide a path to a template file via the --output flag (or the output configuration key). Vale will attempt to find the file at the specified path or resolve it as an asset.

    Data available in templates

    The following data structures are passed to the template execution context:

    Data object

    • Files: A slice of ProcessedFile objects representing files that contain alerts.
    • LintedTotal: An integer representing the total number of files processed by Vale.

    ProcessedFile object

    • Path: The file path of the linted file.
    • Alerts: A slice of core.Alert objects found within the file.
    # Example of how the template data is structured (conceptual)
{{ range .Files }}
File: {{ .Path }}
{{ range .Alerts }}
  [{{ .Severity }}] {{ .Message }}
{{ end }}
{{ end }}
Total files linted: {{ .LintedTotal }}

  5. View verbose alert formatting in Vale

    v3

    When running Vale in a verbose mode, the CLI outputs alerts in a structured, color-coded table format. This view provides detailed information for each violation found in a file, including:

    • Location: The line and column number (line:column).
    • Severity Level: Color-coded indicators for error (red), warning (yellow), and suggestion (blue).
    • Message: The descriptive text of the linting violation.
    • Check: The name of the specific rule/check that triggered the alert.

    At the end of the output, Vale provides a summary of the total number of errors, warnings, and suggestions found across all linted files (or stdin).

  6. View Vale CLI help and options

    v3

    You can access help information through the following commands:

    • General Help: Run vale --help to see a listing of all available CLI options, flags, and commands.
    • Command-Specific Help: To see help for a specific command, use vale <command> --help.
    vale --help
vale <command> --help

  7. Get started with Vale CLI

    v3

    Vale is a syntax-aware command-line linter for prose (supporting Markdown, AsciiDoc, reStructuredText, HTML, etc.).

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

    Basic Usage Patterns:

    • Lint specific files: vale myfile.md
    • Lint multiple files or directories: vale myfile.md myfile1.md mydir1
    • Specify an output format (e.g., JSON): vale --output=JSON [input...]

    Example .vale.ini configuration:

    MinAlertLevel = suggestion

[*]\n	BasedOnStyles = Vale
    vale [options] [input...]
e.g., vale myfile.md myfile1.md mydir1
e.g., vale --output=JSON [input...]

  8. Use the Vale CLI to lint files, directories, or strings

    v3

    Vale can be invoked in several ways depending on the arguments provided:

    1. Lint specific files or directories: Pass the paths as arguments. vale file1.md dir1/

    2. Lint a string directly: If you pass a single argument that does not exist as a file or directory, Vale treats it as a string to be linted. vale "some text in a string"

    3. Lint via STDIN: Pipe content into Vale. If no arguments are provided and STDIN is a character device, Vale reads from standard input. cat file.md | vale

    Exit Codes:

    • 0: No errors found.
    • 1: Errors found (or a test failed).
    • 2: An error occurred during execution (e.g., invalid configuration or unknown command).
    # Linting files
vale file1.md dir1/

# Linting a string
vale "this is a test string"

# Linting via pipe
cat file.md | vale

  9. Format Vale error output using ShowError

    v3

    The ShowError function is used to display Vale errors in specific formats. This is useful when integrating Vale into other tools or custom CLI workflows. It supports three output styles:

    • JSON: Outputs the error details as a JSON object. If the error cannot be parsed into a specific location, it returns a fallback JSON object with Code: "E100" and zeroed numeric fields.
    • line: Outputs a single-line string in the format path:line:code:text. If parsing fails, it falls back to the raw error string.
    • Default: If no recognized style is provided, it outputs the raw error string.

    Note: The function uses core.StripANSI to ensure ANSI escape codes are removed from the text before processing.

    // Example usage of ShowError
// err: the error to display
// style: "JSON", "line", or default
// out: an io.Writer (e.g., os.Stdout)

ShowError(err, "JSON", os.Stdout)
ShowError(err, "line", os.Stdout)

  10. Reference: Hidden Vale CLI Commands

    v3

    The following commands are available but are hidden from the standard --help output. They are primarily used by editor integrations, native messaging hosts, or for advanced debugging.

    host-install: Install the native messaging host.
host-uninstall: Uninstall the native messaging host.
compile: Print a rule's compiled pattern.
run: Run a single rule against a file.
transform: Print a file after its transform.
ls-path: Print the configuration files in scope.
fix: Attempt to automatically fix the given alert.
tag: Print a file's part-of-speech tags.
dc: Alias for `ls-config`.
load: Print a merged pair of configurations.

  12. Handle stdin with extension and path flags

    v3

    When piping content into Vale via stdin, you must tell Vale what the file extension and path would have been so it can apply the correct rules.

    • --ext <extension>: Associates a specific extension with the stdin content (e.g., --ext=.md).
    • --path <path>: Associates a specific file path with the stdin content (e.g., --path=docs/example.md).
    # Example: Linting a string from stdin as a markdown file
echo "This is a test." | vale --ext=.md

# Example: Linting stdin while pretending it is a specific file path
echo "This is a test." | vale --path=docs/readme.md