Quick Start

This guide walks you through setting up Vale on a sample project. You’ll create a configuration file, download a style package, and lint your first document.

Before starting, make sure you’ve installed Vale on your system.

Your First Vale Project

Create a project directory

Create a new directory for this tutorial:

mkdir vale-demo
cd vale-demo

Create a sample Markdown file to lint:

cat > demo.md << 'EOF'
# Getting Started

This document will help you utilize our platform to achieve your goals.
Obviously, it's super easy to get started!

## Key Benefits

- Very unique features
- World-class support
- Cutting-edge technology

Prior to starting, please read the documentation carefully.
EOF

This document contains several style issues we’ll detect with Vale.

Create a Vale configuration

Create a .vale.ini file in your project root:

cat > .vale.ini << 'EOF'
StylesPath = styles
MinAlertLevel = suggestion

Packages = Microsoft

[*.md]
BasedOnStyles = Vale, Microsoft
EOF

Let’s break down this configuration:

StylesPath: Where Vale looks for style packages (relative to .vale.ini)
MinAlertLevel: Minimum severity to display (suggestion, warning, or error)
Packages: External style packages to download
[*.md]: Apply these settings to all Markdown files
BasedOnStyles: Which styles to use (Vale’s built-in style + Microsoft’s style guide)

Download style packages

Vale can automatically download style packages from the Package Hub:

vale sync

You should see output like:

Syncing Microsoft
Synced 1 package(s) to 'styles'.

This creates a styles directory and downloads the Microsoft style guide rules.

The vale sync command reads the Packages key from your .vale.ini and downloads styles from the official Package Hub. You only need to run this once per project (or when adding new packages).

Run Vale

Lint your document:

vale demo.md

Vale will output style violations it found:

demo.md
 3:41  warning  Try to avoid using           Vale.Avoid
                 'utilize'.
 4:1   warning  'Obviously' is a filler      Vale.Hedging
                 word.
 4:16  error    Use 'extremely' instead      Microsoft.Adverbs
                 of 'super'.
 8:8   warning  'Very' is a filler word.     Vale.Hedging
 8:13  warning  'unique' is a                Microsoft.Weasel
                 redundant phrase.
12:1   warning  Use 'before' instead of      Microsoft.Terms
                 'prior to'.

✖ 1 error, 5 warnings and 0 suggestions in 1 file.

Each alert shows:

Location: Line number and column
Severity: error, warning, or suggestion
Message: What Vale found and why it’s an issue
Rule: Which rule detected the issue (format: Style.Rule)

Understanding the Output

Vale’s default output format is designed for humans. Let’s look at each part:

 3:41  warning  Try to avoid using 'utilize'.  Vale.Avoid

3:41: Line 3, column 41 in the file
warning: Severity level (can be error, warning, or suggestion)
Try to avoid using 'utilize': The alert message
Vale.Avoid: The rule that triggered (from the Vale style, rule named Avoid)

You can change the output format:

vale --output=line demo.md
# Output:
# demo.md:3:41:warning:Try to avoid using 'utilize'.:Vale.Avoid

Exploring Configuration Options

Let’s enhance our configuration to demonstrate Vale’s flexibility:

.vale.ini

StylesPath = styles
MinAlertLevel = suggestion

Packages = Microsoft, Google

# Global settings (apply to all files)
Vocab = MyCompany

# Markdown files
[*.md]
BasedOnStyles = Vale, Microsoft, Google

# Only check for errors in blog posts
[blog/*.md]
BasedOnStyles = Vale
MinAlertLevel = error

# Ignore auto-generated files
[api-docs/*.md]
BasedOnStyles =

Configuration breakdown

Packages: Download both Microsoft and Google style guides
Vocab: Use custom vocabulary from styles/config/vocabularies/MyCompany/
[*.md]: Default rules for all Markdown files
[blog/*.md]: Override settings for blog posts (only show errors)
[api-docs/*.md]: Disable linting for auto-generated API docs

Vale supports glob patterns in section headers, letting you apply different rules to different parts of your project. More specific patterns override general ones.

Working with Styles

Vale’s power comes from its extensible style system. You have three options:

Pre-built Packages
Create Your Own
Mix and Match

Download styles from the Package Hub:Popular packages:

Microsoft: Microsoft Writing Style Guide
Google: Google Developer Documentation Style Guide
Readability: Readability metrics and suggestions
proselint: General writing advice
write-good: Plain English suggestions

Add packages to .vale.ini:

Packages = Microsoft, Google, Readability

Then run:

vale sync

Browse all available packages at vale.sh/hub

Create custom rules in the styles directory:

mkdir -p styles/MyStyle
cat > styles/MyStyle/Products.yml << 'EOF'
extends: substitution
message: "Use '%s' instead of '%s'"
level: error
swap:
  product name: ProductName
  company inc: Company, Inc.
  web site: website
EOF

Update .vale.ini to use your style:

[*.md]
BasedOnStyles = MyStyle

Vale supports 12 rule types: existence, substitution, occurrence, repetition, consistency, conditional, capitalization, readability, spelling, sequence, metric, and script.

Combine pre-built packages with custom rules:

# Download external packages
Packages = Microsoft, Google

[*.md]
# Use external packages
BasedOnStyles = Microsoft, Google

# Plus your custom style
BasedOnStyles = Microsoft, Google, MyCompany

Your project structure:

.
├── .vale.ini
├── styles/
│   ├── Microsoft/       # Downloaded
│   ├── Google/          # Downloaded
│   └── MyCompany/       # Custom
│       ├── Branding.yml
│       └── Terms.yml
└── docs/
    └── README.md

Understanding Severity Levels

Vale rules have three severity levels:

suggestion

Optional improvements. Doesn’t fail CI builds.

warning

Recommended changes. May fail CI depending on configuration.

error

Must be fixed. Fails CI builds by default.

Control which levels appear:

.vale.ini

# Show everything
MinAlertLevel = suggestion

# Only show warnings and errors
MinAlertLevel = warning

# Only show errors
MinAlertLevel = error

By default, Vale exits with code 1 if any errors are found. Use --no-exit to suppress this behavior for CI systems that handle exit codes differently.

Common Vale Commands

# Single file
vale README.md

# Multiple files
vale README.md CONTRIBUTING.md

# Directory (recursive)
vale docs/

# Glob patterns
vale --glob='*.{md,txt}' docs/

Real-World Example

Here’s a production-ready configuration for a technical documentation project:

.vale.ini

# Use local styles directory
StylesPath = styles

# Show all issues
MinAlertLevel = suggestion

# Download external packages
Packages = Microsoft, Google, Readability, write-good

# Company-specific terminology
Vocab = Acme

# Default for all files
[*]
BasedOnStyles = Vale

# Documentation files
[docs/**/*.md]
BasedOnStyles = Vale, Microsoft, Google, Readability

# Blog posts (more relaxed)
[blog/**/*.md]
BasedOnStyles = Vale, write-good
MinAlertLevel = warning

# API documentation (strict)
[api/**/*.md]
BasedOnStyles = Microsoft, Google
MinAlertLevel = error

# README files (extra checks)
[README*.md]
BasedOnStyles = Vale, Microsoft, Google, Readability, write-good

# Ignore generated files
[node_modules/**]
BasedOnStyles =

[vendor/**]
BasedOnStyles =

This configuration:

Uses multiple style guides for different content types
Enforces stricter rules on API docs
Relaxes rules for blog posts
Ignores dependency directories
Uses custom vocabulary for company terms

Next Steps

You now have Vale running! Here’s what to explore next:

Configuration Deep Dive

Learn about all .vale.ini options, glob patterns, and inheritance.

Understanding Styles

How Vale’s style system works and how to create custom rules.

Writing Rules

Create your first custom Vale rule with detailed examples.

CI/CD Integration

Add Vale to GitHub Actions, GitLab CI, CircleCI, and more.

Scoping Rules

Control exactly where rules apply in your documents.

Custom Vocabularies

Manage accepted and rejected terminology.

Tips and Tricks

Use vale with stdin

Vale can read from standard input, useful for integrating with other tools:

echo "This is some text to check" | vale

# Or from a file
cat document.md | vale --ext=.md

Use --ext to specify the file extension when reading from stdin. This helps Vale determine the correct parser to use.

Ignore specific lines

Disable Vale for specific lines using comments:

<!-- vale off -->

This text won't be linted by Vale.

<!-- vale on -->

This text will be linted.

Or disable specific rules:

<!-- vale Style.Rule = NO -->

This disables only Style.Rule.

<!-- vale Style.Rule = YES -->

Lint multiple formats

Vale automatically detects file formats:

# Markdown
vale docs/*.md

# HTML
vale site/*.html

# reStructuredText
vale docs/*.rst

# AsciiDoc
vale docs/*.adoc

# Mixed formats
vale docs/

Each format has intelligent parsing to avoid false positives in code blocks and other non-prose content.

Speed up linting with filters

Use .vale.ini to skip directories:

# Ignore everything in these directories
[node_modules/**]
BasedOnStyles =

[vendor/**]
BasedOnStyles =

[build/**]
BasedOnStyles =

Or use .gitignore patterns - Vale respects them by default.

Troubleshooting

Common issues and solutions

No style found

Error: The path 'styles' does not existSolution: Run vale sync to download style packages, or create the styles directory:

mkdir styles
vale sync

Config not found

Error: Unable to locate a configuration fileSolution: Vale searches for .vale.ini in the current directory and parent directories. Either:

Create .vale.ini in your project root
Create a global config at ~/.vale.ini
Use --config to specify a path: vale --config=/path/to/.vale.ini docs/

Rules not applying

Problem: Vale isn’t finding issues you expectDebug steps:

Check which config Vale is using:
```
vale ls-config
```

Verify the file matches your glob pattern:

# This rule: [docs/*.md]
# Matches: docs/README.md
# Doesn't match: docs/guides/example.md (needs docs/**/*.md)

Check rule severity vs. MinAlertLevel:

# Won't show suggestions if MinAlertLevel = warning
MinAlertLevel = suggestion  # Shows everything

Run vale ls-config to see your active configuration, including which rules are loaded and what settings are applied.

Get Started

Core Concepts

Guides

Advanced

Quick Start

Your First Vale Project

Understanding the Output

Exploring Configuration Options

Working with Styles

Understanding Severity Levels

suggestion

warning

error

Common Vale Commands

Real-World Example

Next Steps

Configuration Deep Dive

Understanding Styles

Writing Rules

CI/CD Integration

Scoping Rules

Custom Vocabularies

Tips and Tricks

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

​Your First Vale Project

​Understanding the Output

​Exploring Configuration Options

​Working with Styles

​Understanding Severity Levels

suggestion

warning

error

​Common Vale Commands

​Real-World Example

​Next Steps

Configuration Deep Dive

Understanding Styles

Writing Rules

CI/CD Integration

Scoping Rules

Custom Vocabularies

​Tips and Tricks

​Troubleshooting

Build docs developers (and LLMs) love

Your First Vale Project

Understanding the Output

Exploring Configuration Options

Working with Styles

Understanding Severity Levels

Common Vale Commands

Real-World Example

Next Steps

Tips and Tricks

Troubleshooting