jshwlkr.info

Using cSpell with 11ty

At the time of writing this post this site uses cSpell to manage spell checking. My setup has three components, but you can mix and match as you see fit.

Via the command-line

First install in the project itself:

npm install -D cspell

My config file, a cspell.json file^[1] in the project root, looks like the following:

{
  "version": "0.2",
  "language": "en",
  "dictionaries": ["content"],
  "dictionaryDefinitions": [
    { "name": "content", "path": "./_config/dictionaries/content.txt" }
  ]
}

The dictionaries value is an array of custom dictionary names. The dictionaryDefinitions is an array of custom dictionary names and their path, one pair for each custom dictionary we care to build. The custom dictionary file is just a text file with individual terms on each line.^[2] In this particular case I use an arbitrary "_config" directory to house any kind of configuration that doesn't have to be in the project root.

The script line in the project package.json looks like this:

"scripts": {
    "spell": "cspell _content/**/*.{md,liquid}"
  },

In this case, when I run npm run spell I'm specifically targeting all markdown and liquid files in the "_content" folder and it's sub-folders (which could be any kind of collections folder). Either way, running the command will produce a list of unknown words and the files they're in.

Via VSCode (and VSCodium)

The only thing you need to get CSpell in your VSCode-based editor is install Code Spell Checker by Street Side Software and then tinker with your workspace settings a bit. If you want to copy and paste, add this to your project's .vscode/settings.json file:

{
    "cSpell.enabled": true
}

You will at least want to "cSpell.enabled": true to get CSpell enabled in your editor. This combination of settings should highlight unknown words, allow you to hover over them, select the "quick fix" option, and add the word directly to your custom dictionary. (Which could then be committed as part of your project, or not depending on your opinion.)

Before you commit

Like almost anything that you can run from the command line, you can use Husky and lint-staged to force a spelling check before you make a commit.

npm install -D husky lint-staged
npx husky init

In this case I'm using a .lintstagedrc file in the project root for configuration, which looks like this:

{
  "_content/**/*.{md,liquid}": "cspell"
}

In this case it's just a copy of the package.json command. That's not required however, I could do something more elaborate here if I wanted.

Now in .husky/pre-commit, which should have been created after running npx husky init, we can replace the placeholder (npm run test I believe) added there by default with:

npx lint-staged

This will run lint-staged with the appropriate configuration before you commit, but only on the appropriate files, and prevent the commit if it finds an unknown word.