Spell-checking Markdown with cSpell
Though I haven't written much on this blog, I wanted to add some basic spell-checking to my posts. I looked up "spell-checking markdown" and found an article by TJ Addison that explained how to do this with a tool called cSpell
(the backbone of the somewhat popular Code Spell Checker VSCode extension). Definitely check out TJ's article for a more in-depth explanation of cSpell
and how to use it, but here I'll explain how I set it up for my Eleventy blog.
Installing cSpell
You can use cSpell
without installing it as a dependency by running it with npx
:
npx cspell src/posts/**/*.md
But I opted for installing it permanently as a dev dependency and using an npm script to run it:
npm install cspell --save-dev
{
// ...
"scripts": {
// ...
"spell": "cspell src/posts/**/*.md"
}
}
Configuration
cSpell
allows multiple filenames for its configuration but I went with cspell.config.js
for consistency with my other config files (like eleventy.config.js
and tailwind.config.js
).
To start, set the version to 0.2
(currently always 0.2) and the language to either en
or en-GB
(both are included by default).
module.exports = {
version: '0.2',
language: 'en',
};
There are over 26 other language dictionaries available, but I'm only writing in English so I didn't need to add any others.
An important step is to define specific words to exclude or flag. I told cSpell
to ignore some 11ty-specific terminology and a few other words I use occasionally.
words: [
'eleventy',
'11ty',
'shortcodes',
'webc',
],
flagWords: [],
Dictionaries
In addition to the words
property, you can also define dictionaries - just longer lists of words. I added a dictionary for my GitHub repositories to prevent those from being spell-checked if I ever write about them.
dictionaries: ["repos"],
dictionaryDefinitions: [
{ "name": "repos", "path": "./utils/dicts/repos.txt" },
],
Instead of manually updating my repos.txt
dict, I wrote a script to fetch my repositories from the GitHub API and write them to the file.
#!/usr/bin/env node
const fs = require('node:fs/promises');
const { join } = require('node:path');
async function getRepos() {
try {
const response = await fetch(
'https://api.github.com/users/uncenter/repos',
);
const json = await response.json();
if (Array.isArray(json)) {
fs.writeFile(
join(__dirname, './dicts/repos.txt'),
json.map((repo) => repo.name).join('\n'),
);
} else {
throw new TypeError('Invalid response content.');
}
} catch {
console.error('[cspell:update] Something went wrong.');
}
}
If you're using Netlify, you can run this script and the spell-check script during the build process by adding it to the build
command in your netlify.toml
file (or the GUI on Netlify's website):
[build]
command = "node ./utils/get-repos.js && npm run spell && npm run build"
Ignore patterns
Finally, the config file allows you to define regular expression patterns to ignore. I added patterns to ignore words in Nunjucks expressions, Markdown code blocks and inline code, and proper nouns (words that start with a capital letter).
// ...
ignoreRegExpList: [
'nunjucksExpression',
'markdownCodeBlock',
'markdownInlineCode',
'properNouns',
],
patterns: [
{
name: 'nunjucksExpression',
pattern: /{%.*?%}/gis,
},
{
name: 'markdownCodeBlock',
pattern: /`{3}[\s\S]*?`{3}(?=\n|$)/gi,
},
{
name: 'markdownInlineCode',
pattern: /`[^`]*`/gi,
},
{
name: 'properNouns',
pattern: /(?<=\s|^|[^\w\s])[A-Z][a-z]+(?=\s|$|[^\w\s])/g,
},
],
I'm surprised that there isn't a pattern for Markdown code blocks by default; I was having issues with common JavaScript libraries and methods being flagged as typos. Additionally, I use a few custom shortcodes that kept getting flagged as a typo, so the nunjucksExpression
pattern was a must.
Ignore words in front matter
One other neat thing about cSpell is that you can define words to ignore per file. For example, you could ignore the word supercalifragilisticexpialidocious
in just one file by adding cSpell:ignore supercalifragilisticexpialidocious
as a comment at the top of the file:
---
tags: [...]
title: Magna voluptate officia cillum Lorem proident.
description: Cupidatat excepteur ullamco laboris in veniam qui officia tempor aliquip et commodo.
date: 2000-01-01
# cSpell:ignore supercalifragilisticexpialidocious
---
You don't have to put it in the front matter, but I like to keep my posts as clean & organized as possible and it looks nice there.
Let me know if you have any questions or suggestions!