Consistency is an overlooked and subtle thing in documentation. In my humble opinion, it is very important to name things correctly and every time the same.
This is why a spellchecker to your makes sense, although it will not be perfect. But it can help you be more consistent!
In this post, I will show you how you can add and configure the spellchecker spellchecker-cli to your project. I will also show you how to configure it to run fast, as the default configuration does some unexpected things ;-)
Install spellchecker-cli into your Node.js Project
Use the following command to install it as a dev-dependency
# npm
$ npm install --save-dev spellchecker-cli
#yarn
$ yarn add --dev spellchecker-cli
Add a spellchecker-cli Configuration File
You can configure spellchecker-cli
over command-line parameters, but in my opinion, it is easier to add a configuration file .spellcheckerrc.json
. Create it on the same level as the package.json
.
There are a few things to consider here:
- By default
spellchecker-cli
checks ALL files. Even images. - Files to be scanned/excluded are defined via globby which is based on node-glob
- Start with a small subset as the first run will find a lot of errors
The project I used spellchecker-cli
in, ended up with this configuration file:
1 {
2 "files": [
3 "docs/general/**",
4 "docs/api/**",
5 "!(**/*.gif)",
6 "!(**/*.png)",
7 "!(.spellcheckerrc.json)",
8 "!(spellchecker-dictionary)",
9 "!(./package*)"
10 ]
11 }
- Line 3 + 4: Scan everything in
docs/general/
anddocs/api/
- Line 5 + 6: Exclude every file with the extension
gif
andpng
(Remember the funny defaults I mentioned) - Line 7 + 8: Exclude the spellchecker configuration files
- Line 9: Exclude the node project files
A Dictionary for Allowed Words/Terms Is Necessary
After your first run, you will end up with a lot of errors because you use words/terms out of your specific domain. Unfortunately, spellchecker-cli
does not know them.
For that, you can add a spellchecker-dictionary
-file. The name is up to you as it is configured in the .spellcheckerrc.json
you created earlier like this:
...
"dictionaries": [
"./spellchecker-dictionary"
],
...
The content is unspectacular mostly. Every line marks an allowed word. You can also use Regular Expressions to save typing. But be aware of the saying
Some people, when confronted with a problem, think "I know, I'll use regular expressions." Now they have two problems. - Jamie Zawinski
Add A Run Command/Script in package.json
I am totally lazy when it comes to typing commands. Adding a script to your package.json
is a must ;-)
"spellcheck-project": "spellchecker --config .spellcheckerrc.json"
To run the spellchecker I only need to type npm run spellcheck-project
!
Repository for Reference
I introduced this spellchecker for our docs at work and I am happy with it. You can check our Github-Repository if you want to see a live example.
Conclusion
Adding a spellchecker to your Node.js repository pays off in the long run as your writing becomes more consistent. This helps reduce the confusion of your readers.
With spellchecker-cli
it is straight-forward to add one if you know how to disable the spellchecking for images ;-)
Top comments (0)