The Vale Workflow

A screenshot of the Vale Server v1.3 dashboard
  • Remotely: Remote usage typically involves running Vale on a virtual machine through a Continuous Integration (CI) service.
  • Locally: Local usage typically involves using one of Vale’s editor plugins to provide on-the-fly linting of your content.

Terminology

  • Vale: An open-source, command-line tool that brings code-like linting to prose.
  • Check: Vale’s functionality is exposed through extensible “checks” that perform abstract tasks such as checking the length of certain text segments (e.g., sentences and paragraphs) or searching for a particular token in a text document.
  • Rule: A “rule” is a check that has been given a concrete task — for example, ensuring that sentences contain no more than 25 words.
  • Style: A “style” consists of multiple rules that come together to enforce the guidelines of a certain organization, guide, or application. Within a given style, rules are assigned an ID of the form <style name>.<rule name>.
  • StylesPath: A directory containing all Vale-related files.
  • .vale.ini: An INI-formatted configuration file that serves as the primary means of controlling the behavior of Vale.
  • Vale Server: A commercial desktop application built on top of Vale that brings a refined experience for individual writers, including a fully managed StylesPath and the ability to use local Vale configurations on the web.

The remote environment

The third-party base style [optional]

Installs the latest release of a remotely hosted style (in this case Microsoft) into /styles.

The organization-specific style

Putting it all together: The CI service

├── ci
│ ├── scripts
│ │ └── get-styles.sh
│ └── styles
│ ├── MyOrganization
│ │ └── SpellCheck.yml
│ ├── Microsoft (added to .gitignore)
│ │ ...
│ └── vocab.txt
├── docs
│ ...
├── .vale.ini
├── .travis.yml
├── .gitignore

The local environment

The issues with Vale

  • Managing multiple .vale.ini files can be a pain. If you work on multiple projects (maybe you contribute to a few publications with different guidelines) that don’t have a dedicated .vale.ini, you’re forced to either maintain multiple copies of your global configuration (in $HOME) or update this file whenever you switch projects.
  • Updating your StylesPath is time-consuming. The current find-download-unzip-copy process is far from ideal, especially when managing multiple projects.
  • You can’t use your local Vale configurations on the web. While Vale has existing plugins for text editors, it doesn’t support web-based applications such as Google Docs and web browsers.
  • You can’t customize or override CI-focused configuration files locally. As mentioned in the previous section, it’s common to want only error-level rules enabled for CI environments. This means that’s all you have access to when working on content locally as well.

The case for Vale Server

  1. Install proselint and write-good from the dashboard (if you’re using a third-party base style, you’ll want to install it here too):
Click the Open Dashboard… option from the context menu and then Styles from the sidebar.
See Configuration and Styles for more information.

Summary

  • Vale is ideal for remote CI environments but lacks flexibility when it comes to local editing.
  • Vale Server includes many features that make managing multiple projects and configurations locally easier but isn’t meant for CI environments.
  • Both Vale and Vale Server are designed to allow a high degree of workflow customization: all configuration files are (machine-readable) plain text files that can be incorporated into automation scripts.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store