Writing Articles with Vale

Using Vale in the Vim text editor
Using Vale in the Vim text editor

If you’ve ever done any sort of continuous long form writing, you’ll eventually discover that grammar and spell checking In Microsoft Word, LibreOffice Writer, and other WYSIWYG (What You See Is What You Get) editors. break down and become more of a distraction than a benefit. The “one size fits all” rules for grammar and spell checking cannot hope to account for the indefinite amount of writing styles and constantly evolving word constructions.

Writing is time consuming. How long does it take to write a long form document? The answer not only depends on the writer, but also on the draft and review process which often requires another pair of eyes. Many documents are checked by hired professional editors and others yet Don’t have that luxury. freelancers to write for them.

For the soloist, and or casual writer, building a personal editor or another set of eyes is useful, provided that you’re willing to take on that time investment. The idea is to target a specific writing style, construct the rules, and apply it consistently to your documents.

Vale is an open source program that facilitates this approach — it’s a linter for writing documents. Vale offers no opinion on how to write. You decide that for yourself by Writing rules in YAML (YAML Ain’t Markup Language). a set of grammatical rules and word primitives. Such flexibility allows you to emulate the behaviour of applications like the Hemingway Editor. Vale is not the only program for These linting tools seem to be very popular among tech companies. prose — there are a plethora of similar programs such as textlint, proselint, redpen, or just basic regular expressions.


Vale is available on MacOS, Windows, and Linux based operating systems. major platforms. Install vale for your specific operating system by following the install documentation. Predefined style templates are available for download if you need a starting point.

In my case, a wrapper in ~/.local/bin/vale is setup around the canonical vale to allow Additional argument for running vale --update at the command line level. downloading a few writing style templates and setting up my configuration directory.

#!/bin/sh -eu

mkdir -p "$directory" "$styles";

if [ "${1:-}" = "--update" ]; then
  svn export --force https://github.com/errata-ai/Google/trunk/Google         "$styles/google";
  svn export --force https://github.com/errata-ai/joblint/trunk/Joblint       "$styles/joblint";
  svn export --force https://github.com/errata-ai/Microsoft/trunk/Microsoft   "$styles/microsoft";
  svn export --force https://github.com/errata-ai/proselint/trunk/proselint   "$styles/proselint";
  svn export --force https://github.com/errata-ai/write-good/trunk/write-good "$styles/write-good";

$(which vale --all | grep --invert-match "local/bin" | head -n 1) --config "$directory/vale.ini" "$@";

The vale.ini configuration file is simple. Set a directory containing the styles, adjust the minimum alerting level, and activate the desired writing styles. The typical usage pattern is vale document.txt at the command line.

StylesPath = /home/thedro/.config/vale/styles
MinAlertLevel = suggestion

#BasedOnStyles = google
#BasedOnStyles = joblint
#BasedOnStyles = microsoft
#BasedOnStyles = proselint
#BasedOnStyles = write-good
BasedOnStyles = hemingway
BasedOnStyles = dickens
BasedOnStyles = technical
BasedOnStyles = thedro

Emulating a style requires reading Many popular style guides are out there if you’d rather not. into the patterns of an author’s writing. Here is a snippet of a rule set taken from the write-good style that checks for weasel words.

extends: existence
message: "'%s' is a weasel word!"
ignorecase: true
level: warning
  - absolutely
  - accidentally
  - additionally
  - allegedly
  - alternatively
  - angrily
  - anxiously
  - approximately

Styles are the named directories that contain a set of YAML rule sets. Construct as many rules as you want to complement the desired style.

$ tree -L 3 ~/.config/vale
___ styles
|   |__ google
|   |   |__ Contractions.yml
|   |__ joblint
|   |   |__ Acronyms.yml
|   |__ microsoft
|   |   |__ Wordiness.yml
|   |__ proselint
|   |   |__ Spelling.yml
|   |__ write-good
|       |__ Weasel.yml
|__ vale.ini


This approach obviously requires time as you work to build up a robust rule set for a particular style. The general idea is to correct mistakes, tokenize them as rules, and iterate constantly. You’ll have a tight feedback loop that at a minimum guards the consistency of your writing, and improves your writing speed over time. Perhaps we should take my work in progress clickbait writing style for Not really. sometime.

BasedOnStyles = clickbait
29 March 2021 — Written
29 March 2021 — Updated
Thedro Neely — Creator
writing-with-vale.md — Article

More Content


Web Ring



  1. https://thedroneely.com/git/
  2. https://thedroneely.com/
  3. https://thedroneely.com/posts/
  4. https://thedroneely.com/projects/
  5. https://thedroneely.com/about/
  6. https://thedroneely.com/contact/
  7. https://thedroneely.com/abstracts/
  8. https://ko-fi.com/thedroneely
  9. https://thedroneely.com/tags/writing/
  10. https://thedroneely.com/posts/writing-with-vale/#isso-thread
  11. https://thedroneely.com/posts/rss.xml
  12. https://thedroneely.com/images/writing-with-vale.png
  13. https://en.wikipedia.org/wiki/WYSIWYG
  14. https://github.com/errata-ai/vale
  15. https://en.wikipedia.org/wiki/Open_source
  16. https://yaml.org/
  17. https://hemingwayapp.com/
  18. https://github.com/textlint/textlint
  19. https://github.com/amperser/proselint
  20. https://github.com/redpen-cc/redpen
  21. https://en.wikipedia.org/wiki/Regular_expression
  22. https://thedroneely.com/posts/writing-with-vale/#installation
  23. https://docs.errata.ai/vale/install
  24. https://github.com/errata-ai/styles#available-styles
  25. https://thedroneely.com/posts/writing-with-vale/#code-block-c8b6242
  26. https://thedroneely.com/posts/writing-with-vale/#code-block-c315027
  27. https://docs.errata.ai/vale/styles#existence
  28. https://en.wikipedia.org/wiki/List_of_style_guides
  29. https://github.com/errata-ai/write-good/tree/master/write-good
  30. https://en.wikipedia.org/wiki/Weasel_word
  31. https://thedroneely.com/posts/writing-with-vale/#code-block-6406504
  32. https://thedroneely.com/posts/writing-with-vale/#code-block-f0f28ec
  33. https://thedroneely.com/posts/writing-with-vale/#conclusion
  34. https://thedroneely.com/posts/writing-with-vale/#code-block-de5519e
  35. https://www.thedroneely.com/posts/writing-with-vale.md
  36. https://thedroneely.com/posts/keeping-up-with-open-source/
  37. https://thedroneely.com/archives/tags/
  38. https://thedroneely.com/posts/tweaking-goaccess-for-analytics/
  39. https://git.sr.ht/~sircmpwn/openring
  40. https://drewdevault.com/2022/11/12/In-praise-of-Plan-9.html
  41. https://drewdevault.com/
  42. https://mxb.dev/blog/the-indieweb-for-everyone/
  43. https://mxb.dev/
  44. https://www.taniarascia.com/simplifying-drag-and-drop/
  45. https://www.taniarascia.com/
  46. https://thedroneely.com/posts/writing-with-vale#isso-thread
  47. https://thedroneely.com/posts/writing-with-vale#installation
  48. https://thedroneely.com/posts/writing-with-vale#code-block-c8b6242
  49. https://thedroneely.com/posts/writing-with-vale#code-block-c315027
  50. https://thedroneely.com/posts/writing-with-vale#code-block-6406504
  51. https://thedroneely.com/posts/writing-with-vale#code-block-f0f28ec
  52. https://thedroneely.com/posts/writing-with-vale#conclusion
  53. https://thedroneely.com/posts/writing-with-vale#code-block-de5519e
  54. https://thedroneely.com/posts/kubernetes-in-a-linux-container/
  55. https://thedroneely.com/posts/tailwind-css-and-beyond/
  56. https://thedroneely.com/abstracts/the-myth-of-the-rational-voter/
  57. https://thedroneely.com/abstracts/aria-the-animation/
  58. https://thedroneely.com/posts/nixops-towards-the-final-frontier/
  59. https://thedroneely.com/posts/mixing-php-into-hugo/
  60. https://drewdevault.com/2022/09/16/Open-source-matters.html
  61. https://mxb.dev/blog/make-free-stuff/
  62. https://thedroneely.com/sitemap.xml
  63. https://thedroneely.com/index.json
  64. https://thedroneely.com/resume/
  65. https://gitlab.com/tdro
  66. https://github.com/tdro
  67. https://codeberg.org/tdro
  68. https://thedroneely.com/analytics
  69. https://thedroneely.com/posts/writing-with-vale#
  70. https://creativecommons.org/licenses/by-sa/2.0/
  71. https://thedroneely.com/git/thedroneely/thedroneely.com
  72. https://opensource.org/licenses/GPL-3.0
  73. https://www.thedroneely.com/
  74. https://thedroneely.com/posts/writing-with-vale/#