### Dockerfile for Vale with DITA Support

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

An example Dockerfile demonstrating how to extend the official Vale image to include support for DITA content. Users should pin to a specific version of the base image.

```dockerfile
# Choose a version to pin:
FROM jdkato/vale:v2.15.2
```

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

### Example Project-Level Vale Configuration

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

This INI configuration demonstrates a typical project setup for Vale, specifying the StylesPath, MinAlertLevel, and applying ProjectStyle to Markdown files. It serves as the base configuration that can be locally overridden.

```ini
StylesPath = styles
MinAlertLevel = error

[*.md]
BasedOnStyles = ProjectStyle
```

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

### Vale CLI: Download and install packages

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

Downloads and installs packages for Vale. Refer to the Packages documentation for more details.

```Shell
$ vale sync
```

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

### Run Vale with Docker and Local Components

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

Example of running Vale within a Docker container, mounting local directories for the configuration file (.vale.ini), styles, and documents to be linted. The command assumes a 'styles' directory and a 'fixtures/styles/demo' directory exist in the current working directory.

```bash
docker run --rm -v $(pwd)/styles:/styles \
             --rm -v $(pwd)/fixtures/styles/demo:/docs \
             -w /docs \
             jdkato/vale .
```

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

### Dockerfile: Copy DITA-OT and Set Vale Entrypoint

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

This snippet demonstrates how to copy a local DITA Open Toolkit installation into a container image, set the PATH environment variable to include its binary directory, and define the entrypoint for the container to execute the Vale linter.

```Dockerfile
COPY bin/dita-ot-3.6 /
ENV PATH="/dita-ot-3.6/bin:$PATH"

ENTRYPOINT ["/bin/vale"]
```

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

### Install Vale via Package Manager

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

Installs Vale using the recommended package manager for each operating system. This ensures Vale is added to the system's PATH and allows for easy updates.

```powershell
choco install vale
```

```bash
brew install vale
```

```bash
snap install vale
```

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

### Example: StylesPath Directory Structure

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

This console output illustrates the typical directory structure found within a `StylesPath`. It highlights the special `config` directory, which houses internal Vale resources, and an example user-defined style directory, `write-good`.

```console
$ tree styles
├───config     <-- Special directory
└───write-good <-- A style
```

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

### Configure Vale Rule Header Field Examples

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

Examples of setting various header fields within a Vale rule's YAML configuration.

```YAML
extends: existence
```

```YAML
message: "Don't use '%s' headings."
```

```YAML
level: warning
```

```YAML
scope: heading
```

```YAML
link: https://example.com
```

```YAML
limit: 3
```

```YAML
vocab: false
```

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

### Install Docutils for reStructuredText Support

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

To enable Vale to process reStructuredText content, the `docutils` package, which provides the `rst2html` executable, must be installed. This command installs the necessary Python package using pip.

```bash
$ pip install docutils
```

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

### Vale INI Configuration for Complete Package

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

Example .vale.ini configuration for a complete Vale package, showing how to reference the local 'styles' path and include other external packages.

```ini
# This is subfolder included in our .zip archive.
StylesPath = styles

# Complete packages can include other, externally-defined
# packages.
Packages = proselint

# Normal configuration ...
[*.{md,adoc}]
Test.Rule = YES
```

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

### Configure Packages in .vale.ini

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

This example demonstrates how to define packages and apply styles in a Vale configuration file. It shows how to include multiple packages globally and apply specific styles to Markdown files.

```ini
Packages = Google, write-good

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

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

### Server Initialization Parameters

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

Describes the configuration parameters available for initializing the server, including options for Vale installation, output filtering, configuration path, and synchronization behavior. These parameters control the server's behavior upon startup.

```APIDOC
initializationParams:
  installVale:
    type: boolean
    default: true
    description: Automatically install and update Vale to a vale_bin folder in the same location as vale-ls. If false, the vale executable needs to be available on the user’s $PATH.
  filter:
    type: string
    default: None
    description: An output filter to apply when calling Vale.
  configPath:
    type: string
    default: None
    description: An absolute path to a .vale.ini file to be used as the default configuration.
  syncOnStartup:
    type: boolean
    default: true
    description: Runs vale sync upon starting the server.
```

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

### Install mdx2vast CLI for MDX Processing

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

This command installs the `mdx2vast` command-line interface globally using npm. `mdx2vast` is an external program required by Vale to process MDX content. Ensure that the executable is available in your system's PATH after installation.

```bash
$ npm install -g mdx2vast
```

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

### Vale Vocabulary Folder Structure Example

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

This snippet illustrates the recommended folder structure for Vale vocabularies, showing how 'accept.txt' and 'reject.txt' files are organized within named vocabulary directories under '<StylesPath>/config/vocabularies'.

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

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

### Example Python Code for Tree-sitter Parsing in Vale

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

A simple Python function demonstrating comments and a docstring. This code serves as an input example for Tree-sitter, showcasing how Vale can parse and extract specific syntactic elements from source code.

```python
# This a comment.
def hello(name: str) -> str:
    """
    This is a docstring.
    """
    return f"Hello, {name}!"
```

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

### Define Packages with Local and Remote Sources

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

This configuration example shows how to set a `StylesPath` and `MinAlertLevel`, and how to include packages from both a named official source ('Microsoft') and a direct URL to a `.zip` file. It also demonstrates applying a style to a specific file (`README.md`).

```ini
StylesPath = .github/styles
MinAlertLevel = suggestion

Packages = Microsoft,
https://github.com/errata-ai/errata.ai/releases/download/v1.0.0/Test.zip

[README.md]
BasedOnStyles = Vale
```

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

### Vale Package Manager Availability

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

This section details the availability and status of the Vale linter across different package managers, providing direct links to their respective documentation pages.

```APIDOC
Package Managers:
  PyPI:
    Name: project/vale
    Status: active
    Documentation: https://pypi.org/project/vale/
  NPM:
    Name: @ocular-d/vale-bin
    Status: unmaintained
    Documentation: https://www.npmjs.com/package/%40ocular-d/vale-bin
```

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

### Gitignore Configuration for Vale StylesPath

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

Example .gitignore rules to selectively ignore parts of the Vale StylesPath while tracking specific local components like a 'Base' vocabulary.

```gitignore
# We want to ignore our StylesPath *except* for our local
# vocabularies/Base directory.

.github/styles/*
!.github/styles/config/

.github/styles/config/*
!.github/styles/config/vocabularies/

.github/styles/config/vocabularies/*
!.github/styles/config/vocabularies/Base
```

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

### Vale CLI: Match files with glob pattern

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

Uses a glob pattern to select files for processing within a directory. Consult the Globbing guide for pattern examples.

```Shell
$ vale --glob='*.md' some-dir
```

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

### Example Vale `existence` Rule Configuration

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

A YAML configuration example demonstrating how to define an `existence` rule in Vale. This snippet shows how to set a custom message, warning level, enable case-insensitivity, and specify a list of tokens to check for existence.

```yaml
extends: existence
message: Consider removing '%s'
level: warning
ignorecase: true
tokens:
  - appears to be
  - arguably
```

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

### Pull Vale Docker Image

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

Pulls the official Vale Docker image from Docker Hub. This image provides a containerized environment for running Vale.

```bash
docker pull jdkato/vale
```

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

### Example Local Vale Configuration Override

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

This INI configuration shows how to create a local override for Vale. It defines a new StylesPath, adds write-good to Packages, and applies write-good as a BasedOnStyles for Markdown files, demonstrating how local settings merge or override global ones.

```ini
StylesPath = localpath

Packages = write-good

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

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

### Configure Basic Vale `substitution` Check

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

Example YAML configuration for a Vale `substitution` check, demonstrating how to define a message, level, and simple `swap` rules for common word replacements.

```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
```

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

### Example: Relative StylesPath Configuration in .vale.ini

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

This INI configuration demonstrates how to define a relative `StylesPath` within your `.vale.ini` file. It also shows how to apply a specific style, `MyStyle`, to Markdown files by referencing it from the `StylesPath`.

```ini
# Here's an example of a relative path:
#
# .vale.ini
# ci/
# ├── vale/
# │   ├── styles/
StylesPath = ci/vale/styles

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

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

### Markdown Example with Ignored Inline Code

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

This Markdown example illustrates how `IgnoredScopes` works. The text within the backticks (which typically renders as `<code>` HTML tags) will not be checked by Vale, even if it contains potential issues, because `code` is listed in `IgnoredScopes`.

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

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

### Vale Styles Directory Structure Example

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

This console output demonstrates the recommended nested folder structure for organizing Vale styles. It illustrates how a 'styles' directory can contain subdirectories like 'base', 'blog', and 'docs', each holding various YAML rule files, allowing for modular and organized style management.

```console
$ tree styles
styles/
├── base/
│   ├── ComplexWords.yml
│   ├── SentenceLength.yml
│   ...
├── blog/
│   ├── TechTerms.yml
│   ...
└── docs/
├── Branding.yml
```

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

### Example JSON Data for Dasel Processing in Vale

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

A sample JSON structure illustrating the kind of structured data that Vale can process using Dasel. This data includes a title, version, and an array of features, each with its own title and description.

```json
{
	"title": "Vale",
	"version": "3.0.0",
	"features": [
		{
			"title": "Views",
			"description": "Customize the file-processing pipeline with Views."
		},
		{
			"title": "Styles",
			"description": "Define custom linting rules with Styles."
		}
	]
}
```

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

### Enable or disable specific Vale styles in AsciiDoc

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

Provides examples of how to explicitly enable or disable individual Vale styles (e.g., `StyleName1`, `StyleName2`) within an AsciiDoc document using `<!-- vale StyleName = YES/NO -->` comments. This allows for selective application of style guides.

```adoc
pass:[<!-- vale StyleName1 = YES -->]
pass:[<!-- vale StyleName2 = NO -->]
```

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

### Tengo Script Example: Convert CamelCase to snake_case

Source: https://vale.sh/docs/fixers/suggest

An example Tengo script (`CamelToSnake.tengo`) that transforms a matched string from CamelCase to snake_case. It utilizes the `text` module for regular expression replacement and string manipulation, outputting the result in the `suggestions` array.

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

// `match` is provided by Vale and represents 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 required by Vale and represents the script's output.
suggestions := [made]
```

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

### Vale Rule Header Fields Reference

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

Defines the configurable header fields for Vale rules, including their purpose, requirements, default values, and example usage.

```APIDOC
RuleHeaderField:
  name: string
  required: boolean
  default: string
  description: string
  example: string

Fields:
- name: extends
  required: true
  default: N/A
  description: The name of the check to extend in the particular rule.
  example: extends: existence
- name: message
  required: true
  default: N/A
  description: The message to display when the rule is triggered. Each extension point has different formatting options.
  example: message: "Don't use '%s' headings."
- name: level
  required: false
  default: suggestion
  description: The severity of the rule. The available options are suggestion, warning, and error.
  example: level: warning
- name: scope
  required: false
  default: text
  description: The scope of the rule.
  example: scope: heading
- name: link
  required: false
  default: N/A
  description: A URL to associate with the rule. This is useful for providing more information about the rule.
  example: link: https://example.com
- name: limit
  required: false
  default: N/A
  description: The maximum number of times the rule can be triggered in a single file.
  example: limit: 3
- name: vocab
  required: false
  default: true
  description: If set to false, any active vocabularies will be disabled for the rule.
  example: vocab: false
```

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

### Vale CLI: Do not load global configuration

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

Instructs Vale to ignore the global configuration file, relying only on local or specified configurations. Useful for isolated testing or specific project setups.

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

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

### Vale Vocabulary File Entry Format (Regex)

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

This snippet shows the plain-text format for 'accept.txt' and 'reject.txt' files, where each line represents a case-sensitive regular expression entry. Lines starting with '#' are treated as comments.

```regex
first
[pP]y.*\b
third
```

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

### Configure `message` for Multiple Suggestions in Vale `substitution`

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

Example of configuring the `message` field in a Vale `substitution` check to support multiple alternative suggestions, using a pipe delimiter for display.

```yaml
extends: substitution
# NOTE: We don't quote the first '%s':
message: Consider using %s instead of '%s.'
level: warning
```

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

### Example Markdown with Ignored Code Block

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

This Markdown example illustrates how content within a fenced code block (specifically a Python block) is ignored by Vale when `SkippedScopes` is configured to include `pre` tags. The text outside the code block will still be processed by Vale, while the code block itself will be skipped.

```markdown
This is a sentence that contains normal text.

```python
# This is a code block.
print("Hello, world!")
```

Another normal sentence.
```

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

### Minimal Hunspell Dictionary (.dic) Example

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

This snippet shows a basic Hunspell dictionary file. It defines '1' as the number of words in the dictionary and 'software/M' as the root word 'software' with affix code 'M', indicating that variations derived from 'M' are accepted.

```plaintext
1
software/M
```

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

### YAML Configuration for Vale Script-Based Rule

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

Example YAML configuration for a Vale rule that leverages the `script` extension. It demonstrates how to specify the rule's message, an external link, the content scope (`raw`), and the filename of the Tengo script (`MyScript.tengo`) to be executed.

```yaml
extends: script
message: 'Consider inserting a new section heading at this point.'
link: https://tengolang.com
scope: raw
script: MyScript.tengo
```

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

### Example Vale Consistency Check Configuration

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

This YAML configuration demonstrates how to set up a `consistency` check in Vale. It defines a custom message, sets the alert level to error, enables case-insensitive matching, and specifies pairs of words (e.g., 'advisor'/'adviser', 'centre'/'center') where only one should appear within the checked scope.

```yaml
extends: consistency
message: "Inconsistent spelling of '%s'."
level: error
ignorecase: true
# We only want one of these to appear.
either:
  advisor: adviser
  centre: center
```

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

### Vale `tokens` Key and Compiled Regex Example

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

Illustrates the usage of the `tokens` key within a Vale rule, defining a list of phrases to be checked for existence. It also shows the resulting compiled regular expression, demonstrating how Vale transforms these tokens into a word-bounded, non-capturing group for pattern matching.

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

```regex
(?i)(?m)\b(?:appears to be|arguably)\b
```

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

### Example Vale Style Definition using YAML Substitution

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

This YAML snippet demonstrates how to define a custom style rule in Vale. It uses the `extends` keyword to specify the `substitution` extension point, which is used to ensure the correct usage of technical terms within prose. This allows authors to enforce consistent terminology across documents.

```YAML
# `extends` specifies the extension point you're using. Here, we're
# using `substitution` to ensure correct usage of some techincal and
```

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

### Example YAML Front Matter Block

Source: https://vale.sh/docs/formats/front-matter

This YAML snippet illustrates a typical front matter block containing 'title', 'description', and 'author' fields. Vale parses these fields and automatically generates specific scopes for each, such as 'text.frontmatter.title', enabling precise rule application.

```yaml
---
title: 'My document'
description: "A short summary of the document's purpose."
author: 'John Doe'
---
```

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

### Vale Vocabulary Case-Insensitive Regex Examples

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

This snippet provides two methods for creating case-insensitive vocabulary entries: using '(?i)' to mark the entire pattern as insensitive or providing multiple acceptable options with character classes.

```regex
(?i)MongoDB
[Oo]bservability
```

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

### Vale Vocabulary Case-Sensitive Entry Example

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

This snippet illustrates a case-sensitive vocabulary entry. "MongoDB" will only match "MongoDB" exactly, and variations like "mongoDB" will be flagged as errors.

```regex
MongoDB
```

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

### Example Vale INI Configuration for TokenIgnores

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

This INI configuration snippet illustrates how to use the `TokenIgnores` key. It sets a `StylesPath`, applies a base style to Markdown files, and defines two regex patterns for `TokenIgnores` to prevent Vale from checking specific inline content, such as `$+...+$` and `:math:`...``. This is useful for ignoring custom syntax that doesn't have an associated HTML tag.

```ini
StylesPath = styles

[*.md]
BasedOnStyles = Vale

TokenIgnores = ($+[^
$]+$+), (:math:`.*`)
```

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

### Example View definition for OpenAPI document fields

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

This YAML snippet defines a Vale View that extracts specific fields from an OpenAPI document. It uses the `dasel` engine to select `info.title`, `info.description`, and `servers.all().description` as separate markdown scopes for linting.

```yaml
engine: dasel
scopes:
  - name: title
    expr: info.title
    type: md

  - expr: info.description
    type: md

  - expr: servers.all().description
    type: md
```

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

### Tengo Script Example: Paragraph Counting

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

A Tengo script demonstrating how to count paragraphs within a document, identify sections exceeding a defined limit, and populate the `matches` array. It utilizes the `text` module for string and regex operations, and handles code blocks by removing them before processing.

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

matches := []
// at most 3 paragraphs per section
p_limit := 3

// Remove all instances of code blocks
// since we don't want to count inter-block
// newlines as a new paragraph.
document := text.re_replace("(?s) *(\n```.*?```\n)", scope, "")

count := 0
for line in text.split(document, "\n") {
    if text.has_prefix(line, "#") {
        count = 0 // New section; reset count
    } else if count > p_limit {
        start := text.index(scope, line)
        matches = append(matches, {begin: start, end: start + len(line)})
        count = 0
    } else if text.trim_space(line) == "" {
        count += 1
    }
}
```

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

### Configure Vale Capitalization Check with Prefix

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

Example YAML configuration for a Vale `capitalization` check that enforces sentence casing while allowing a constant prefix to be ignored during case conversion.

```YAML
extends: capitalization
message: "'%s' should be sentence-cased."
scope: heading
match: $sentence
```

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

### Configure Vale Capitalization Check for Title Case

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

Example YAML configuration for a Vale `capitalization` check, enforcing title case for headings using the AP style and specifying certain words to be ignored as exceptions.

```YAML
extends: capitalization
message: "'%s' should be in title case"
level: warning
scope: heading
# $title, $sentence, $lower, $upper, or a pattern.
match: $title
# AP or Chicago; only applies when match is set to
# $title.
style: AP
exceptions:
  - ABC
  - add
```

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

### Example Vale Rule Definition in YAML

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

This YAML snippet showcases a typical Vale rule, extending an existing check. It defines a custom message, provides a link for more information, sets the alert level to 'warning', targets 'heading' scope, and includes an action to remove specific punctuation. It also specifies tokens for pattern matching.

```yaml
# An example rule from the "Microsoft" style.
extends: existence
message: "Don't use end punctuation in headings."
link: https://docs.microsoft.com/en-us/style-guide/punctuation/periods
nonword: true
level: warning
scope: heading
action:
  name: edit
  params:
    - remove
    - '.?!'
tokens:
  - '[a-z0-9][.?!](?:\s|$)'
```

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

### Initialize Vale configuration

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

This snippet demonstrates the steps to initialize a Vale project after creating the `.vale.ini` file. It shows how to navigate to the project directory, create the configuration file, run `vale sync` to initialize styles, and then lint a file like `README.md`.

```bash
$ cd some-project
# You'll need to create this file
$ cat .vale.ini
...
$ vale sync
...
$ ls styles
...
$ vale README.md
```

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

### Rust Doc Comment with Embedded Markdown Example

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

This Rust code snippet illustrates how documentation comments (///) can contain embedded Markdown, including fenced code blocks. This pattern is common for generating API documentation and can be linted by tools like Vale.

```Rust
impl Person {
    /// Creates a person with the given name.
    ///
    /// # Examples
    ///
    /// ```
    /// // You can have rust code between fences
    /// // inside the comments If you pass --test
    /// // to `rustdoc`, it will even test it for
    /// // you!
    /// use doc::Person;
    /// let person = Person::new("name");
    /// ```
    pub fn new(name: &str) -> Person {
        Person {
            name: name.to_string(),
        }
    }
}
```

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

### Configuring IgnoredScopes in Vale's .ini file

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

This configuration snippet demonstrates how to set the `IgnoredScopes` key in your Vale configuration file (`.vale.ini`). It specifies `code` and `tt` as tags whose content should be ignored by Vale's checks. The `BasedOnStyles` line indicates the style guide being used for Markdown files.

```ini
StylesPath = styles

IgnoredScopes = code, tt

[*.md]
BasedOnStyles = Vale
```

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

### Enable or Disable Specific Styles in Org

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

This example demonstrates how to individually enable or disable specific Vale styles within an Org file using '# vale StyleName = YES' or '# vale StyleName = NO'. This allows fine-grained control over which styles are active.

```Org
# vale StyleName1 = YES
# vale StyleName2 = NO
```

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

### Example Content for a Vale Ignore File

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

This snippet demonstrates the plain-text content of an ignore file used by Vale. Each line contains a word (e.g., 'destructuring', 'transpiler') that will be excluded from spell checks. These files are referenced in Vale's configuration to customize ignored terms.

```plaintext
destructuring
transpiler
```

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

### Configure Vale styles for Markdown files in .vale.ini

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

This ini configuration snippet for .vale.ini sets the base path for styles and applies the 'Vale' style to all Markdown files (*.md). It's a common setup for defining style rules based on file extensions.

```ini
StylesPath = styles

[*.md]
BasedOnStyles = Vale
```

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

### Exclude files using negated glob pattern with Vale CLI

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

This sh command demonstrates how to use the --glob flag with a negated pattern (!) to exclude specific file types. The example shows how to process all files except those with .md or .py extensions when running the vale command.

```sh
# Match all files except those with a `.md` or `.py` extension.
$ vale --glob='!**/*.{md,py}' path/to/files
```

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

### Configure IgnoredClasses in Vale INI

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

This configuration snippet demonstrates how to use the `IgnoredClasses` key in a Vale `.ini` file. It specifies a comma-separated list of HTML class names that Vale should ignore when performing linting checks on content. The example also shows how to set a `StylesPath` and apply styles based on file type, such as Markdown.

```ini
StylesPath = styles

IgnoredClasses = my-class, another-class

[*.md]
BasedOnStyles = Vale
```

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

### Hunspell Affix (.aff) File Example

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

This snippet illustrates a basic Hunspell affix file. It defines a suffix rule 'SFX M Y 1' for affix code 'M', where 'Y' indicates cross-productibility and '1' indicates one rule. A specific rule 'SFX M 0 's .' is defined to add ''s' to words with affix code 'M' without removing any base word characters and without conditions, resulting in acceptance of words like 'software' and 'software’s'.

```plaintext
SET UTF-8

SFX M Y 1
SFX M   0     's         .
```

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

### Directory Structure of a Complete Vale Package

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

Illustrates the typical directory layout for a complete Vale package, including .vale.ini and a 'styles' folder with rules, dictionaries, scripts, and vocabularies.

```console
MyPackage
├── .vale.ini
└── styles
    ├── MyStyle
    │   └── MyRule.yml
    └── config
        ├── dictionaries
        │   └── MyDic.dic
        ├── scripts
        │   └── MyScript.tengo
        └── vocabularies
            └── MyVocab
                ├── accept.txt
                └── reject.txt
```

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

### Example of Vale Built-in Repetition Check

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

This Markdown snippet demonstrates how Vale's built-in `repetition` check identifies repeated words, even across markup boundaries. In this specific example, it would flag 'Mermaid' if it were repeated, or any other word, illustrating its ability to catch common grammatical errors.

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

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

### Unzip a Style-Only Vale Package

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

This console command demonstrates how to unzip a style-only Vale package, such as 'write-good.zip'. The output shows the typical directory structure and content of such a package, including style definition files and metadata.

```console
$ unzip write-good.zip
Archive:  write-good.zip
   creating: write-good/
  inflating: write-good/README.md
  inflating: write-good/Cliches.yml
  inflating: write-good/ThereIs.yml
  inflating: write-good/Weasel.yml
  inflating: write-good/TooWordy.yml
  inflating: write-good/Passive.yml
  inflating: write-good/So.yml
  inflating: write-good/Illusions.yml
  inflating: write-good/E-Prime.yml
  inflating: write-good/meta.json
```

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

### Vale CLI: Print default configuration directory locations

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

Shows the paths of the default configuration directories used by Vale.

```Shell
$ vale ls-dirs
```

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

### Vale INI Configuration for Vocabulary Reference

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

This INI configuration snippet demonstrates how to specify the 'StylesPath' and reference a defined vocabulary (e.g., "Blog") within a Vale project's '.vale.ini' file, applying it to all files ('[*]').

```ini
StylesPath = styles

Vocab = Blog

[*]
BasedOnStyles = Vale, MyStyle
```

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

### Disable a Specific Vale Rule in reStructuredText

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

This example shows how to disable a particular Vale rule, such as `Style.Redundancy`, for a specific section of reStructuredText content. The rule is then re-enabled using `.. vale Style.Redundancy = YES`.

```rst
.. vale Style.Redundancy = NO

This is some text ACT test

.. vale Style.Redundancy = YES
```

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

### Use Custom Template for Vale CLI Output

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

Shows how to use a custom Go template file for Vale's output by passing its path to the --output flag. The template file must be located in <StylesPath>/config/templates.

```bash
$ vale --output='template.tmpl' somefile.md
```

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

### Vale INI Configuration for Package Loading Order

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

Demonstrates how the 'Packages' directive defines the loading order, where later packages override earlier ones, and local configuration takes precedence.

```ini
Packages = pkg1, pkg2

# Local configuration ...
[*.{md,adoc}]
Test.Rule = YES
```

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

### Configure Vale pre-commit hook in YAML

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

This YAML configuration demonstrates how to set up a pre-commit hook to run Vale. It includes two hooks: one to synchronize Vale's internal data ('vale sync') and another to run Vale with specific output and alert level arguments.

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

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

### Vale CLI: Print supported environment variables

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

Lists all environment variables that Vale recognizes and utilizes.

```Shell
$ vale ls-vars
```

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

### Configure Vale Vocabulary and Styles in INI

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

This INI configuration snippet demonstrates how to set up custom vocabularies and define which styles should respect them within Vale. It shows the `StylesPath` setting, the `Vocab` key for naming a vocabulary, and the `BasedOnStyles` key to link the vocabulary to specific styles like 'Vale' and 'MyStyle', ensuring automatic exception handling.

```ini
StylesPath = "..."

# Here's were we define the exceptions to use in *all*
# `BasedOnStyles`.
Vocab = Some-Name

[*]
# 'Vale' and 'MyStyle' automatically respect all
# custom exceptions.
#
# The built-in 'Vale' style is required for using
# `Vale.Terms`, `Vale.Avoid`, or `Vale.Spelling`.
BasedOnStyles = Vale, MyStyle
```

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

### Vale Terminology Substitution Rule Configuration

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

This YAML configuration defines a `substitution` rule for Vale, enforcing consistent brand-specific terminology. It specifies a custom error message, sets the severity to `error` to fail CI builds, enables case-insensitive matching, and provides a `swap` map to correct common variations of terms like 'Node.js' and 'PostgreSQL' to their preferred forms.

```YAML
# brand-specifc terminology.
extends: substitution
# `message` allows you to customize the output shown to your users.
message: Use '%s' instead of '%s'.
# We're setting this rule's severity to `error`, which will cause
# CI builds to fail.
level: error
# We're using case-insensitive patterns.
ignorecase: true
swap:
  "(?:LetsEncrypt|Let's Encrypt)": Let's Encrypt
  'node[.]?js': Node.js
  'Post?gr?e(?:SQL)': PostgreSQL
  'java[ -]?scripts?': JavaScript
  linode cli: Linode CLI
  linode manager: Linode Manager
  linode: Linode
  longview: Longview
  nodebalancer: NodeBalancer
```

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

### Vale Core Configuration Settings

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

Defines the application-wide settings for Vale, including paths for styles, package management, vocabulary loading, and alert level control. These settings appear at the top of the configuration file and apply globally to the Vale application.

```APIDOC
Name: StylesPath
  Type: string
  Description: Path to all Vale-related resources.
Name: Packages
  Type: string[]
  Description: List of packages to download and install.
Name: Vocab
  Type: string[]
  Description: List of vocabularies to load.
Name: MinAlertLevel
  Type: enum
  Description: Minimum alert level to display.
Name: IgnoredScopes
  Type: enum
  Description: List of inline-level HTML tags to ignore.
Name: SkippedScopes
  Type: enum
  Description: List of block-level HTML tags to ignore.
```

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

### Example YAML Configuration for occurrence Check

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

This YAML configuration demonstrates how to use the `occurrence` check to limit the number of commas per sentence. It sets a maximum of 3 commas and flags an error if exceeded.

```yaml
extends: occurrence
message: 'More than 3 commas!'
level: error
# Here, we're counting the number of times a comma appears
# in a sentence.
#
# If it occurs more than 3 times, we'll flag it.
scope: sentence
max: 3
token: ','
```

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

### Specify Output Style for Vale CLI

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

Demonstrates how to use the --output flag to specify one of Vale's built-in output styles (line, JSON, CLI) for a given file.

```bash
$ vale --output=line README.md
```

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

### Disable a Specific Vale Rule in Org

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

This example shows how to temporarily turn off a particular Vale rule, such as 'Style.Redundancy', for a section of an Org file. The rule is re-enabled afterward using '# vale Style.Redundancy = YES'.

```Org
# vale Style.Redundancy = NO

This is some text ACT test

# vale Style.Redundancy = YES
```

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

### Go Template for Vale Output Style Re-implementation

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

This Go template re-implements Vale's default output style. It iterates through linted files and their alerts, categorizing them by severity (error, warning, suggestion) and displaying details like line number, message, and check. Finally, it summarizes the total counts of errors, warnings, and suggestions across all processed files.

```Go Template
{{- /* Keep track of our various counts */ -}}

{{- $e := 0 -}}
{{- $w := 0 -}}
{{- $s := 0 -}}
{{- $f := 0 -}}

{{- /* Range over the linted files */ -}}

{{- range .Files}}
{{$table := newTable true}}

{{- $f = add1 $f -}}
{{- .Path | underline | indent 1 -}}

{{- /* Range over the file's alerts */ -}}

{{- range .Alerts -}}

{{- $error := "" -}}
{{- if eq .Severity "error" -}}
    {{- $error = .Severity | red -}}
    {{- $e = add1 $e  -}}
{{- else if eq .Severity "warning" -}}
    {{- $error = .Severity | yellow -}}
    {{- $w = add1 $w -}}
{{- else -}}
    {{- $error = .Severity | blue -}}
    {{- $s = add1 $s -}}
{{- end}}

{{- $loc := printf "%d:%d" .Line (index .Span 0) -}}
{{- $row := list $loc $error .Message .Check | toStrings -}}

{{- $table = addRow $table $row -}}
{{end -}}

{{- $table = renderTable $table -}}
{{end}}
{{- $e}} {{"errors" | red}}, {{$w}} {{"warnings" | yellow}} and {{$s}} {{"suggestions" | blue}} in {{$f}} {{$f | int | plural "file" "files"}}.
```

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

### Unzip Config-Only Vale Package

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

Demonstrates how to extract a config-only Vale package, which contains a single .vale.ini file.

```console
$ unzip Hugo.zip
Archive:  Hugo.zip
   creating: Hugo/
  inflating: Hugo/.vale.ini
```

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

### Regex Filter for Ignoring Words

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

This regular expression defines a pattern to ignore words starting with 'py' (case-insensitive) during spell checking, such as 'PyYAML'. It is typically used within a Vale configuration to customize spell-check behavior.

```regex
[pP]y.*\b
```

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

### Control Vale rules within MDX comments

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

This MDX example demonstrates how to use the custom `CommentDelimiters` to enable/disable Vale rules within the document. It shows how to turn off all rules (`vale off`), turn them back on (`vale on`), and specifically disable a rule like `vale.Redundancy`.

```mdx
{/* vale off */}

This is some text ACT test

This is some text ACT test

{/* vale on */}

{/* vale vale.Redundancy = NO */}

This is some text ACT test

{/* vale vale.Redundancy = YES */}
```

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

### Vale Global Configuration File Search Locations

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

Lists the default operating system-specific locations where Vale searches for its global configuration file (`.vale.ini`). This file is always loaded in addition to project-specific configurations, providing a layer for project-agnostic customization.

```APIDOC
OS: Windows
  Search Locations: %LOCALAPPDATA%\vale\.vale.ini
OS: macOS
  Search Locations: $HOME/Library/Application Support/vale/.vale.ini
OS: Unix
  Search Locations: $XDG_CONFIG_HOME/vale/.vale.ini
```

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

### Use Regex Keys in Vale `substitution` `swap`

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

Demonstrates how to use regular expressions as keys in the `swap` mapping of a Vale `substitution` check, allowing for more flexible pattern matching.

```yaml
swap:
  '(?:give|gave) rise to': lead to
```

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

### Vale CLI: Print current configuration as JSON

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

Outputs the active configuration options of Vale in JSON format.

```Shell
$ vale ls-config
```

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

### Enable Multiple Styles for Markdown Files

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

This snippet demonstrates how to enable multiple styles (Vale and MyStyle) for Markdown files (`.md`) by setting `BasedOnStyles` in the `[*.md]` section of the `.vale.ini` file. It also shows the `StylesPath` configuration.

```ini
StylesPath = styles

[*.md]
BasedOnStyles = Vale, MyStyle
```

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

### Enable or Disable Specific Vale Styles in reStructuredText

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

This example shows how to explicitly enable or disable individual Vale styles within reStructuredText content. Directives like `.. vale StyleName1 = YES` and `.. vale StyleName2 = NO` provide granular control over which styles are active.

```rst
.. vale StyleName1 = YES
.. vale StyleName2 = NO
```

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

### Vale CLI Environment Variables Reference

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

This section documents the environment variables that can be used to configure the Vale CLI's behavior. These variables allow overriding default paths and settings.

```APIDOC
VALE_CONFIG_PATH:
  Description: Override the default search process by specifying a .vale.ini file.
VALE_STYLES_PATH:
  Description: Specify the location of the default StylesPath.
```

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

### Enable or disable specific Vale styles in HTML

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

Explains how to individually enable or disable specific Vale styles (e.g., 'StyleName1', 'StyleName2') within HTML content using '<!-- vale StyleName = YES/NO -->'. This provides granular control over which style guides are active.

```html
<!-- vale StyleName1 = YES -->
<!-- vale StyleName2 = NO -->
```

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

### Simplified YAML Configuration for `replace` action

Source: https://vale.sh/docs/fixers/replace

Shows a simplified YAML configuration for the `replace` action. When rules extend `substitution` or `capitalization`, the `params` array is automatically populated, requiring only the `name`.

```yaml
action:
  name: replace
```

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

### Vale.sh Configuration: Custom Regex with 'raw' Key

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

Demonstrates how to use the 'raw' key in Vale.sh configurations to define custom regular expressions. This key provides fine-grained control over patterns, allowing for complex expressions without post-processing. Multiple entries in 'raw' are concatenated, enhancing readability for intricate patterns.

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

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

### Apply Vale Rule to Unprocessed Document Content

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

Vale typically converts documents to HTML and applies a scoping system before running rules, which can alter results for rules targeting markup. This example shows how to bypass this processing and apply a rule to the entire, unprocessed document content by setting the 'scope' property to 'raw'.

```YAML
extends: existence
message: Consider removing '%s'
scope: raw
tokens:
  - some token
```