top of page
Post: Blog2 Post
Search
Writer's pictureNikhila Jain
Aug 293 min read

How to Install Vale linter for Documentation in VS Code

Vale is a versatile and customizable command-line linter designed to enforce consistent style and grammar in your documentation. Whether you're following Microsoft's guidelines, Google's documentation style, or creating your own, Vale can help maintain quality and coherence in your writing by setting vale in Visual Studio Code (VS Code).. This guide helps you set up Vale linter for Documentation in VS Code, from installation to configuration.


Prerequisites

Before you begin, ensure you have the following prerequisites in place:


  • Visual Studio Code. If you haven't installed it yet, get it from the official website.

  • Node.js and npm. Download and install Node.js and npm from Node's official website.

  • Clone your repository and set it up in your Visual Studio Code editor.


Install Vale

Let's kick things off by installing Vale and configure the style guide formats like Microsoft, Google, or your own style guide. To install Vale, follow these steps:


  • Launch the terminal or command prompt on your machine.

brew install vale

  • After installation, verify that Vale is installed correctly by checking its version:

vale -v

If installed successfully, this command will display the current version of Vale.


Get Style Guides from GitHub Repository

Vale is hosted as a GitHub repository, offering a variety of preconfigured style guides, including popular options like Google and Microsoft. These style guides come with predefined rules and best practices, ready to be used out of the box. By leveraging these resources, you can quickly integrate professional writing standards into your documentation.


Download Style Guides from GitHub

  • Visit the Vale GitHub repository.

  • Navigate to the styles folder, where you'll find predefined style guides for Microsoft, Google, and other standards.

  • Download the styles folder and any additional configuration files (like .vale.ini) from the repository.


Add the Style Guides to Your Repository

  • Place the downloaded styles folder in a directory within your repository, such as .github/styles or any other desired folder.

  • You can use the .vale.ini file downloaded from the vale repository directly and modify it to suit your project’s structure, or create your own .vale.ini file


Create or Update the .vale.ini File

  • If you didn't download a .vale.ini file, create one in the root of your repository.

  • Set the StylesPath to point to the folder where you placed the styles.

  • Configure files like accept.txt and reject.txt available under styles/config/vocabularies/technical. These files enable you to:

    • Bypass Specific Terms: Use accept.txt to add words that should not trigger linting issues.

    • Enforce Specific Terms: Use reject.txt to add terms that should be flagged during linting.


    Here's a sample .vale.ini file that you can use or customize for your project:

# The path to the folder where your style guides are stored
StylesPath = .github/styles

# The minimum alert level to display: suggestion, warning, or error
MinAlertLevel = warning

# The path to the accepted and rejected terms
Vocab = technical

# Define the file formats on which style guides rules will be applied
[*.md]

# Define the style guide rules to be applied
BasedOnStyles = Google, Microsoft

Set up Vale linter for Documentation in VS Code

To integrate Vale with your Visual Studio Code editor, follow these steps:


  • In Visual Studio Code, go to the Extensions marketplace, search for Vale VSCode extension, and install the extension.

  • Open extension settings, choose the workspace tab, and set the .vale.ini path as ${workspaceFolder}/.vale.ini. Ensure that the workspaceFolder points to the root of your documentation project where the .vale.ini file resides.

  • Once configured, save the extension settings.


Test Linter

Time for a quick test to ensure everything is running smoothly:


  • Open an existing markdown file in VS Code.

  • Verify if the linter detects any issues based on the defined style guides.

  • You can also create a new file and add the below text to check the linting:

# Test linter Issues
In this document, we will explore various writing issues. For instance, the issue related to the title of the document.

## Common Issues
- **Omitted Words**: Sentences which have words like "we" and "our":
	- If you face issues, contact our support team.
    - We appreciate any information that can help us improve our support.
- **Use of Exclamation Marks**: Use of exclamation marks in statements like "This is fantastic!"

By following these steps, you have successfully integrated Vale linter into your Visual Studio Code editor, enhancing the quality and consistency of your documentation project. Now, write with confidence knowing that your documentation meets the desired standards!


Happy documenting!

Comments

bottom of page