Vale – software to help you write with a consistent tone and style

In Operation

Vale offers a powerful extension system that doesn’t need knowledge of any programming languages. It uses collections of individual YAML files to enforce specific writing constructs. These collections are referred to as styles and are organized in a nested folder structure at a user-specified location.

Once the style guide is configured, Vale checks text against all the rules in that style guide. It outputs suggestions, warnings, and errors on the terminal.

Other features include:

• Supported Formats:
  • Markdown – GitHub-Flavored Markdown support is built in. Vale ignores indented blocks, fenced blocks, and code spans by default.
  • HTML5 support – Vale ignores script, style, pre, code, and tt tags by default.
  • reStructuredText – supported with the external program rst2html.
  • AsciiDOC – supported through the external program Asciidoctor.
  • DITA – supported through the DITA Open Toolkit.
  • XML – supported through the external program xsltproc
  • Org support is built in. Org is an Emacs major mode for keeping notes, authoring documents, and more.
  • Many programming languages.
• “Syntax aware” which means Vale can apply rules to and ignore certain sections of text. This functionality is implemented through a scoping system.
• Integration with other tools. Receive real-time feedback based on your own style guide while you write in VS Code, Sublime Text, Vim, Emacs, and more.
• Supports GitHub Actions, CircleCI, or any other CI/CD service.

Summary

Vale is an excellent tool if you write text in Markdown or other markup languages. It helps you produce text files which fit in with an organization’s requirements.

Vale has good support for many markup formats. This is a big time-saver as it avoids syntax-related false positives and intelligently exclude code snippets from prose-related rules.

It takes time you build your own styles and fine-tune your configuration, but there’s lots of help available. For example, the project provides a package hub which lets you browse, learn from, or build upon styles from RedHat, Google, and others. But there’s still need for refinement such as creating a custom vocabulary to avoid Vale flagging words as errors when they are not.

Website: vale.sh
Support: GitHub Code Repository
Developer: Joseph Kato
License: MIT License

Vale is written in Go. Learn Go with our recommended free books and free tutorials.

Pages in this article:
Page 1 – Introduction and Installation
Page 2 – In Operation and Summary