Blog proofreading: links, spelling, and grammar

Publishing a blog post should be quick and easy. While in the zone and writing down an idea frantically, it can be easy to slip up and make an error. This could be an invalid link, repeating a sentence, or spelling a word incorrectly. While nobody is expecting an immense level of editorial scrutiny, most readers would prefer a blog free of those errors over one with them. Fortunately, there are some nifty tools that can help with the proofreading process so that those errors are quickly caught before hitting publish. These tools will work for any editing and publishing flow where there is access to the files from the command line.

Checking links with lychee

Link errors are introduced in two ways: author error, or link rot. Lychee aims to fix both. Lychee is run against the text file containing the recently written blog post to highlight any links that are not valid, enabling correction before publishing. Lychee can be installed through a wide variety of package managers, including cargo.

lychee my-blog-post.md

This will produce a nice coloured output showing the results of each link check. The below is the same command, but run on all files at once for the blog. Note, lychee checks links quickly, so being careful of running into rate limits is important. Checking one post at a time is usually better.

Broken links can then be corrected (if possible) or removed. Replacing the broken link with one from the Internet Archive could be a good solution if available.

Adding lychee to a cd/ci pipeline

Lychee can automatically run on a push to a particular branch, or as a pre-commit action. The setup for that would look something like this:

CI action (example taken from a woodpecker configuration)

links:
    image: lycheeverse/lychee:0.17.0
    depends_on: []
    commands:
      - lychee . -v

Pre-commit

repos:
  - repo: https://github.com/lycheeverse/lychee.git
    rev: v0.17.0
    hooks:
      - id: lychee
        args: ["--no-progress", "--exclude", "file://"]

Checking prose and spelling with Vale

In the same way that lychee can be run against a single file, Vale can also be used to check a text file. This provides suggestions for how to improve the writing, either because of spelling or because of adherence to a particular style guide.

vale my-blog-post.md

Running it against this post shows that I cannot seem to spell against, and that I write in a passive voice. Importantly, this isn’t running any AI or contacting any cloud, all work is done locally.

Vale requires some setup before it can be run for the first time, I won’t cover those instructions here, the documentation explains everything to get setup. Brandon Rozek has a great blog post that covers further details.

Combining both of these actions into a single script

Both of these tools are just command line tools, so they can be combine into a single convenient bash script. Running the bash script is a healthy middle ground between annoying ci pipelines that stop you from merging, and having to remember the exact commands each time. Since results are cached in a file named .lycheecache, it makes sense to add that file to .gitignore as well as part of the setup process.

lychee $1 --scheme https --cache
vale $1 

The bash script can then be placed in the root of the repository and used on a post.

./proof-read content/posts/my-blog-post.md