How to Install Vale linter for Documentation in VS Code

I found myself spending a disproportionate amount of time on manual documentation reviews. Issues such as style inconsistencies, passive voice, and terminology drift rarely appeared during writing—they surfaced late in the process, often during editorial review. By then, fixes were slow, repetitive, and costly.

Manual reviews don’t fail because they’re unnecessary; they fail because they happen too late. When feedback arrives after content is already written, teams end up correcting patterns instead of preventing them.

Vale addresses this problem earlier in the workflow. It is a command-line linter designed for prose and works independently of the text editor you use. Its impact, however, is amplified when integrated with VS Code. Vale flags documentation issues as you write, using the same immediate feedback loop developers expect from code linters.

In this guide, I’ll show you how to set up Vale in VS Code to catch these issues automatically.

What you need before installing Vale

Before we begin, ensure you have:

• Visual Studio Code installed
• A documentation project (or any Markdown files to lint) or set up your documentation repository in Visual Studio Code editor.
• Terminal access (VS Code's built-in terminal works perfectly)
• About 10 minutes of your time

Install Vale

Installing Vale is straightforward and doesn’t require any editor-specific setup. Start by installing Vale on your system using the method appropriate for your operating system.

1. Launch the terminal or command prompt on your machine, and use the command based on your operating system:

   • macOS

     brew install vale
     

   • Windows

     choco install vale
     

   • Linux: Ubuntu/Debian

     sudo apt-get install vale
     

   • Linux: RHEL/CentOS

     sudo yum install vale
     

2. Verify the installation:

   vale -v
   

You should see the version number pop up if everything's installed correctly. I remember doing a little happy dance when I saw that first successful version check!

Set Up Vale in Your Project

Now that Vale is installed, let's configure it for your documentation project. This setup will help you maintain consistent writing standards across your documentation.

1. Navigate to your project directory:

   cd your-project-directory
   

2. Create the .vale.ini file:

   touch .vale.ini
   

3. Open the .vale.ini file and add this configuration:

   # Path to your styles
   StylesPath = .github/styles
   
   # Minimum alert level to show (suggestion, warning, or error)
   MinAlertLevel = warning
   
   # Custom vocabulary configuration
   Vocab = technical
   
   # Rules for Markdown files
   [*.md]
   BasedOnStyles = Google, Microsoft
   

4. Set up custom vocabulary (optional but recommended):
   Create these files under .github/styles/config/vocabularies/technical/:

   • accept.txt - Add words that should be accepted (bypass linting)
   • reject.txt - Add terms that should always be flagged

   This is particularly useful for technical terms, product names, or company-specific terminology.

Configure VS Code Integration

To get real-time feedback while writing documentation, let's integrate Vale with VS Code:

1. Install the Vale VSCode extension:

   • Open VS Code Extensions view (Ctrl+Shift+X or Cmd+Shift+X)
   • Search for "Vale"
   • Install the "Vale" extension by errata-ai

2. Configure the extension:

   • Open VS Code Settings (Ctrl+, or Cmd+,)
   • Search for "Vale"
   • Set Vale CLI: Path to just vale (it should be in your PATH)
   • Set Vale CLI: Config to ${workspaceFolder}/.vale.ini
   • Save the settings

Test Your Setup

Let's verify everything is working correctly:

1. Create a test markdown file (e.g., test-vale.md) with the following content:

   # Test Document for Vale Linter
   
   This document contains intentional issues to test Vale's functionality.
   
   ## Common Issues to Detect
   
   - **Omitted Words**: 
     - "Contact our support team if you face any issues."
     - "We appreciate your feedback on our documentation."
   
   - **Excessive Punctuation**:
     - This is fantastic!!!
     - Don't do this!!!!
   

2. Save the file and look for underlines or indicators in the editor gutter

3. Hover over underlined text to see Vale's suggestions

Customizing Rules

Vale's true power comes from its customization. Here's how to tailor it to your needs:

1. Style Customization:

   • Edit the style rules in .github/styles/
   • Each style has its own .yml file with configurable rules

2. Vocabulary Management:

   • Add technical terms to accept.txt to prevent false positives
   • Use reject.txt to flag deprecated or discouraged terms

3. Rule Severity:
   Adjust the MinAlertLevel in .vale.ini to control which issues are shown:

   • suggestion: All issues (most verbose)
   • warning: Only warnings and errors (default)
   • error: Only critical issues

Common Issues and Solutions

As you start using Vale, you'll likely encounter some common warnings. Here's how to handle them:

1. Omitted Words: Vale flags words like "we" and "our" by default to encourage more direct, user-focused writing.

   # These will trigger warnings:
   - Contact our support team for assistance.
   - We recommend using this approach.
   
   # Better alternatives:
   - Contact the support team for assistance.
   - The recommended approach is...
   

2. Excessive Punctuation: Vale helps maintain a professional tone by flagging excessive exclamation marks.

   # This will trigger a warning:
   This feature is amazing!!!
   
   # Better alternatives:
   This feature is powerful.
   This feature offers significant benefits.
   

3. Passive Voice: Vale helps identify passive constructions that can make writing less direct.

   # This will trigger a warning:
   The documentation was updated by the team.
   
   # Better alternative:
   The team updated the documentation.
   

Final Thoughts

Vale has transformed how I handle documentation by catching issues as I write, saving hours of manual review time. The real power lies in preventing problems before they reach reviews, ensuring consistent, high-quality documentation.

With Vale handling the style checks, I can focus on creating clear, effective content rather than getting bogged down in manual proofreading. It's become an essential tool in my documentation workflow.

Pro Tip: Start with the default rules and gradually add custom ones based on your team's needs. This makes adoption smoother and helps identify the most valuable rules for your workflow.