Creating Custom Styles

Vale styles are collections of rules organized into reusable packages. This guide shows you how to create, structure, and share custom styles.

What is a Style?

A style is a directory containing Vale rules (YAML files) that enforce a specific writing standard. Each style has:

A directory name (the style name)
One or more rule files (.yml extension)
Optional configuration files

styles/
└── MyStyle/
    ├── Headings.yml
    ├── Acronyms.yml
    ├── Spelling.yml
    └── meta.json

Creating a Basic Style

Create the style directory

Create a directory in your StylesPath:

mkdir -p styles/MyCompany

The directory name becomes your style name (MyCompany).

Add your first rule

Create a rule file in the style directory:

styles/MyCompany/Terms.yml

extends: substitution
message: "Use '%s' instead of '%s'"
ignorecase: true
level: error
action:
  name: replace
swap:
  MyCompany: MyCompany Inc.
  mycorp: MyCompany

Enable the style

Reference the style in your .vale.ini:

.vale.ini

StylesPath = styles
MinAlertLevel = suggestion

[*]
BasedOnStyles = MyCompany

Test the style

Run Vale to test your style:

vale "Welcome to mycorp!"

Style Organization

Directory Structure

A well-organized style follows this structure:

styles/
└── MyCompany/
    ├── meta.json              # Optional: Style metadata
    ├── Vocabulary/            # Vocabulary files
    │   ├── accept.txt
    │   └── reject.txt
    ├── Dictionaries/          # Custom dictionaries
    │   └── en_US/
    │       ├── custom.dic
    │       └── custom.aff
    ├── Acronyms.yml          # Individual rules
    ├── Headings.yml
    ├── Spelling.yml
    ├── Terms.yml
    └── Tone.yml

Naming Conventions

Follow these conventions for rule files:

Use PascalCase for rule names: Acronyms.yml, PassiveVoice.yml
Make names descriptive: HeadingCapitalization.yml not Heading.yml
Group related rules with prefixes: Spelling*.yml, Terms*.yml

Rule names appear in alerts as StyleName.RuleName, so choose names that make sense to your users.

Built-in Default Rules

Vale provides built-in rules in the Vale style. You can reference these in your config:

.vale.ini

StylesPath = styles

[*]
BasedOnStyles = Vale, MyCompany

# Configure built-in rules
Vale.Avoid = YES
Vale.Terms = YES
Vale.Repetition = YES
Vale.Spelling = YES

The built-in Vale rules are defined in internal/check/definition.go:

Vale.Avoid: Blocks specific tokens
Vale.Terms: Enforces terminology from vocabularies
Vale.Repetition: Detects repeated words
Vale.Spelling: Spell checks with dictionary support

Creating a Vocabulary

Vocabularies define accepted and rejected terms for your style.

Create vocabulary files

Create the Vocab directory structure:

mkdir -p styles/MyCompany/Vocab
touch styles/MyCompany/Vocab/accept.txt
touch styles/MyCompany/Vocab/reject.txt

Add accepted terms

List one term per line in accept.txt:

styles/MyCompany/Vocab/accept.txt

MyCompany
API
JavaScript
TypeScript

These terms will be:

Excluded from spell checking
Used as exceptions in rules with vocab: true

Add rejected terms

List terms to avoid in reject.txt:

styles/MyCompany/Vocab/reject.txt

MyCompany Inc
Javascript
Typescript

Reference the vocabulary

Enable the vocabulary in .vale.ini:

.vale.ini

StylesPath = styles
Vocab = MyCompany

[*]
BasedOnStyles = MyCompany

Terms in accept.txt are automatically added as exceptions to all rules with vocab: true (the default for most rule types).

Rule Reuse with Exceptions

Use the vocab and exceptions keys to make rules flexible:

styles/MyCompany/Abbreviations.yml

extends: existence
message: "Define abbreviations on first use"
level: warning
vocab: true  # Ignore terms from accept.txt
tokens:
  - '\b[A-Z]{2,}\b'
exceptions:
  # Always ignore these
  - API
  - URL
  - HTTP
  - HTTPS

When vocab: true, the rule automatically ignores all terms from your vocabulary’s accept.txt.

Style Metadata

Create a meta.json file to provide style information:

styles/MyCompany/meta.json

{
  "name": "MyCompany",
  "description": "MyCompany writing style guide",
  "author": "MyCompany Documentation Team",
  "version": "1.0.0",
  "url": "https://github.com/mycompany/vale-style",
  "license": "MIT",
  "vale_version": ">=3.0.0"
}

Packaging for Distribution

To share your style, create a package compatible with Vale’s sync command.

Create a GitHub repository

Create a repository with this structure:

vale-mycompany/
├── README.md
├── LICENSE
├── MyCompany/
│   ├── meta.json
│   ├── Vocab/
│   │   ├── accept.txt
│   │   └── reject.txt
│   └── *.yml (your rules)
└── .vale.ini (example config)

Create a release

Create a GitHub release with your style directory as a .zip file:

cd vale-mycompany
zip -r MyCompany.zip MyCompany/
gh release create v1.0.0 MyCompany.zip

Configure the package

Users can install your style via the Packages key:

.vale.ini

StylesPath = styles

Packages = https://github.com/mycompany/vale-mycompany/releases/latest/download/MyCompany.zip

[*]
BasedOnStyles = MyCompany

Sync the package

Users run vale sync to download and install:

vale sync
# Synced 1 package(s) to 'styles'.

The .zip file must contain a directory with the exact style name. Vale extracts this to StylesPath.

Using Multiple Styles

Combine multiple styles in your configuration:

.vale.ini

StylesPath = styles

Packages = Microsoft, write-good, MyCompany

[*]
BasedOnStyles = Vale, Microsoft, MyCompany

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

[*.{js,jsx,ts,tsx}]
BasedOnStyles = Microsoft

Vale applies all specified styles, and later styles can override earlier ones.

Style Inheritance

While Vale doesn’t support direct style inheritance, you can reference rules from other styles:

.vale.ini

[*.md]
BasedOnStyles = BaseStyle, MyStyle

# Override specific rules
BaseStyle.Headings = NO
MyStyle.Terms = YES

Testing Your Style

Create test cases for your style:

MyCompany/
├── Acronyms.yml
├── test/
│   ├── Acronyms/
│   │   ├── valid.md
│   │   └── invalid.md
│   └── .vale.ini

Test files:

MyCompany/test/Acronyms/valid.md

The World Health Organization (WHO) is a specialized agency.

WHO has been active since 1948.

MyCompany/test/Acronyms/invalid.md

WHO has been active since 1948.

Test configuration:

MyCompany/test/.vale.ini

StylesPath = ../..
MinAlertLevel = suggestion

[*]
BasedOnStyles = MyCompany

Run tests:

cd MyCompany/test
vale Acronyms/invalid.md
# Should show: Acronyms/invalid.md:1:1: MyCompany.Acronyms: 'WHO' has no definition

vale Acronyms/valid.md
# Should show no errors

Publishing to the Vale Style Library

To share your style with the community:

Create a GitHub repository following the package structure above
Add comprehensive documentation in your README
Submit to the styles repository: https://github.com/errata-ai/styles
Follow the submission guidelines in the repository

Popular styles include:

Microsoft: Microsoft Writing Style Guide
Google: Google Developer Documentation Style Guide
write-good: Naive linter for English prose
proselint: Prose linting from professional writers

Advanced: Style Configuration

Create a default configuration file for your style:

MyCompany/.vale.ini

# Users can reference this as a starting point
StylesPath = styles
MinAlertLevel = suggestion

[*]
BasedOnStyles = MyCompany

# Example format-specific config
[*.md]
BasedOnStyles = Vale, MyCompany

[*.{rst,rest}]
BasedOnStyles = MyCompany

Example: Complete Style

Here’s a complete minimal style:

MyCompany style files

styles/MyCompany/Terms.yml

extends: substitution
message: "Use '%s' instead of '%s'"
ignorecase: true
level: error
vocab: true
action:
  name: replace
swap:
  javascript: JavaScript
  api endpoint: API endpoint
  rest api: REST API

styles/MyCompany/Headings.yml

extends: capitalization
message: "'%s' should be in sentence case"
level: warning
scope: heading
match: $sentence
vocab: true

styles/MyCompany/Spelling.yml

extends: spelling
message: "Did you mean '%s'?"
level: error
vocab: true
action:
  name: suggest
  params: [spellings]

styles/MyCompany/Vocab/accept.txt

MyCompany
JavaScript
TypeScript
API
REST

.vale.ini

StylesPath = styles
Vocab = MyCompany
MinAlertLevel = suggestion

[*]
BasedOnStyles = MyCompany

Best Practices

Start with vocabulary: Define your terminology first
Test thoroughly: Create test cases for each rule
Document your rules: Add clear messages and links
Version your style: Use semantic versioning
Provide examples: Include example configuration files
Use consistent naming: Follow established naming conventions
Enable vocab by default: Set vocab: true on most rules
Package for distribution: Make it easy for others to install

Get Started

Core Concepts

Guides

Advanced

Creating Custom Styles

What is a Style?

Creating a Basic Style

Style Organization

Directory Structure

Naming Conventions

Built-in Default Rules

Creating a Vocabulary

Rule Reuse with Exceptions

Style Metadata

Packaging for Distribution

Using Multiple Styles

Style Inheritance

Testing Your Style

Publishing to the Vale Style Library

Advanced: Style Configuration

Example: Complete Style

Best Practices

Next Steps

Writing Rules

CI Integration

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

​What is a Style?

​Creating a Basic Style

​Style Organization

​Directory Structure

​Naming Conventions

​Built-in Default Rules

​Creating a Vocabulary

​Rule Reuse with Exceptions

​Style Metadata

​Packaging for Distribution

​Using Multiple Styles

​Style Inheritance

​Testing Your Style

​Publishing to the Vale Style Library

​Advanced: Style Configuration

​Example: Complete Style

​Best Practices

​Next Steps

Writing Rules

CI Integration

Build docs developers (and LLMs) love

What is a Style?

Creating a Basic Style

Style Organization

Directory Structure

Naming Conventions

Built-in Default Rules

Creating a Vocabulary

Rule Reuse with Exceptions

Style Metadata

Packaging for Distribution

Using Multiple Styles

Style Inheritance

Testing Your Style

Publishing to the Vale Style Library

Advanced: Style Configuration

Example: Complete Style

Best Practices

Next Steps