Published 15 minutes ago

João has been covering the tech world for over 7 years, with a heavy focus on laptops and the Windows ecosystem. I also love all things tech and videogames, especially Nintendo, which he’s always happy to talk about.

Prior to joining XDA in 2021, he worked at Neowin: https://www.neowin.net/news/poster/jo%C3%A3o-carrasqueira/

There’s no shortage of ways to write down your notes, journals, and knowledge bases on your computer. A popular tool is Obsidian, which saves your notes in Markdown format, though there are plenty of other tools using Markdown if you want something different.

But one thing these programs often overlook is the ability to keep your notes looking clean, concise, and well-written. That’s where Vale comes in. It’s yet another terminal-based tool, but it’s also a great one for helping ensure your text looks as good as it should.

Related

Getting started with Vale

It takes a little bit of setup

When I say Vale is a text editor, I mean it in a slightly more literal sense, in that it isn’t a program for writing or editing text, but instead it checks your existing texts for potential errors, lack of clarity, and other problems.

Getting started with Vale was a little intimidating at first, but once I got a grasp on what I was doing, it wasn’t too bad. You can install vale easily by using a package manager such as Chocolatey on Windows, Homebrew on macOS, or Snapcraft on Linux. There are other options on each platform, though, and I personally used Winget for my Windows testing.

After that, you need to create a .vale.ini file in the same folder where you want Vale to do its work. This file tells Vale which styles and rules to apply to the files you’re going to analyze. The easiest way to get started with this is to use the Config Generator, which offers a handful of styles to choose from out of the box, but you can also add more styles manually based on this list. Then, once you have the .vale.ini file, you can open the terminal inside that folder and run vale sync to download the necessary style files to enforce the checks you want.

Once this is all done, you can have Vale analyze your files using the vale command. Vale can analyze Markdown files, AsciiDoc, HTML, and a few other formats. Interestingly, it does not seem to support plain text files (TXT) files.

Related

How Vale works

Simple, yet very capable

When you run the vale command on a file or folder, it will check the entire text for any problems that match the rules it includes. In addition to multiple styles, Vale also has its own built-in spellchecker, so it can also help you fix typing mistakes. Detections can be labeled as errors, warnings, or suggestions, and it can recommend fixes such as removing or replacing the offending word or term.

All of this is determined by the styles and tools in your project folder, which are downloaded when you run vale sync. All of a style’s rules are stored inside YAML files, which means you can easily see and modify them using a basic text editing program such as Notepad, which is an interesting glimpse behind the scenes.

For example, the write-good style includes a few YAML files, including one focused on cliché phrases. All this one does is detect one of the specified phrases (called tokens) and tell you you might want to replace it. These include things like "chip off the old block" or "down in the dumps".

But then there’s the proselint style, which comes with a pretty big set of rules, and one of them has to do with animal labels. This rule doesn’t just detect specific words, but it also recommends replacements. In this case, it’s detecting terms such as "bull-like" and recommending a replacement like "taurine".

The YAML files also define whether fixes should be shown as suggestions or errors, what kind of check should be performed, and the scope of the checks, such as only checking headers, image captions, and so on. If you really want to, you can change these files yourself or create new YAML files for additional rules to essentially create your own style guide.

Related

I self-hosted my own Grammarly alternative using LanguageTool

It’s a fantastic addition to my stack of writing applications

You can add your own vocabulary

Stop pointless suggestions

In addition to styles, Vale supports a lot more configuration options through its .ini file, which you can always change for different projects. At its most basic, you can add certain exceptions or rules, such as limiting the minimum alert level to be displayed. For example, if you only want to see errors and not suggestions or warnings, you can set the MinAlertLevel variable to error in the .ini file.

But what you might find most interesting is that option to add "vocabularies" to your checks. These are lists of words and terms related to a specific project, where you might want to accept or reject certain words regardless of what’s specified in the styles you’ve selected.

When I first ran Vale, I used a document that featured the names of various Pokémon, which obviously aren’t real words. Vale detected all of these as spelling errors, which wasted some of my time as I had to scroll past all of these errors to see the information I want. By creating a vocabulary folder and file (or files) and then adding it to the .ini file, you can define words that are automatically accepted regardless of any other rules in the styles you’ve added.

My example is fairly specific, but this can be useful when talking about all kinds of products, since a lot of brands and product names aren’t proper words. Because vocabularies are independent from styles, you can maintain custom lists for different projects without having to recreate the styles themselves each time.

Related

Vale is an essential tool for writers

At first glance, Vale can seem both simple and complicated, but once you understand what it’s all about, there’s no denying that it’s extremely helpful for keeping your texts looking professional, clear, and correct. You can tailor it to your specific needs so that it works for your projects, and it generates its report quickly and in a way that’s easy to analyze and interpret. It’s yet another great tool that shows how much can be done with the terminal, and I highly recommend checking it out.

Image credit: Joseph Kato

Vale