From 77232e4af337d13901bfb921b8d4e946d6c7b82b Mon Sep 17 00:00:00 2001 From: Brandon Rozek Date: Tue, 26 Nov 2024 21:03:48 -0500 Subject: [PATCH] New Post --- content/blog/vale-linter-human-prose.md | 75 +++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 content/blog/vale-linter-human-prose.md diff --git a/content/blog/vale-linter-human-prose.md b/content/blog/vale-linter-human-prose.md new file mode 100644 index 0000000..3b9ac5f --- /dev/null +++ b/content/blog/vale-linter-human-prose.md @@ -0,0 +1,75 @@ +--- +title: "Linting my blog posts with Vale" +date: 2024-11-27T16:29:30-05:00 +draft: false +tags: [] +math: false +medium_enabled: false +--- + +How do you write *good*? + +For some, the answer is Grammarly. This, however, falls short to me for the following reasons: + +- Needing to rely on some third party service. Seriously, what if I want to draft my blog posts without Internet? +- Not configurable. Leave me alone, sometimes I like writing **my way**. +- Where's my beautiful terminal application? + +I use [Vale](https://vale.sh/) ([GitHub](https://github.com/errata-ai/vale)) a linter for human prose. It runs locally on my computer ✔, is configurable by defining a rule set ✔, and offers not only a beautiful CLI application ✔, but even offers integrations to editors like VSCode. + +To provide useful feedback, we'll need a strong collection of rules. Like a crazy person, I went onto the [Vale package hub](https://vale.sh/hub/) and looked at the rules of many different packages and compiled the ones I liked into [my own package](https://github.com/brandon-rozek/vale) for us to use. + +All we need to do is specify the package in our Vale config. To see where this lives, you can run `vale ls-dirs`. For example, on my computer it is at `~/.config/vale/.vale.ini` + +```ini +StylesPath = /home/rozek/.local/share/vale/styles + +Vocab = brozek + +MinAlertLevel = suggestion + +Packages = https://github.com/Brandon-Rozek/vale/releases/download/0.1.0/brozek.zip + +[*] +BasedOnStyles = Vale, brozek +``` + +By default, Vale includes a spell-checker. As a technical writer, I often talk about products which Vale claims are typos. We can force Vale to not complain by creating a [Vocabulary](https://vale.sh/docs/topics/vocab/) (fancy word for dictionary). + +`/config/vocabularies/brozek/accept.txt` + +``` +BTRFS +[Bb]oolean +systemd +Zulip +``` + +These vocabularies are case-sensitive, which while may seen like a weird choice, I find useful in keeping capitalization consistent. To specify that something is not case sensitive you'll need to put square brackets around the upper and lower-case letter. For example, case-insensitive b is `[Bb]`. + +With all this configured, we can then sync the configuration rules to our machine. + +```bash +vale sync +``` + +Then, lint a blog post! + +```bash +vale vale-linter-human-prose.md +``` + +``` + vale-linter-human-prose.md + 14:48 warning Remove 'Seriously' if it's not brozek.Adverbs + important to the meaning of + the statement. + 20:70 suggestion Try to keep sentences short (< brozek.SentenceLength + 30 words). + 48:91 warning Remove 'really' if it's not brozek.Adverbs + important to the meaning of + the statement. +``` + +From there you can choose which suggestions to keep and which to ignore ;) +