Spell Check for Documentation — Complete Guide

Automated spell checking for documentation catches typos, misspellings, and inconsistent terminology before publication. Learn how to configure cspell, Hunspell, and integrate spell checking into CI/CD.

What You'll Learn

You will learn how to set up automated spell checking with cspell, manage custom dictionaries, handle technical terms and code snippets, and integrate spell checking into your documentation pipeline.

Why It Matters

Typos erode reader trust. If a documentation page has spelling errors, developers question whether the technical content is also incorrect. Automated spell checking catches these errors before they reach readers.

Real-World Use

DodaTech runs cspell across all 15,000+ pages. Custom dictionaries include product names (Doda Browser, DodaZIP, Durga Antivirus Pro), technical terms, and programming language keywords.

flowchart LR
  A[Markdown File] --> B[cspell]
  B --> C{Custom Dictionary?}
  C -->|Yes| D[Check Against Dictionary]
  C -->|No| E[Flag as Unknown]
  D --> F[Pass or Fail]
  E --> F
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Setting Up cspell

Install cspell:

npm install -g cspell

Create a cspell.json configuration file:

{
  "version": "0.2",
  "language": "en-US",
  "words": [
    "DodaTech",
    "DodaZIP",
    "DodaBrowser",
    "Durga",
    "Antivirus",
    "backend",
    "frontend",
    "configurable",
    "authentication",
    "authorization"
  ],
  "flagWords": ["color"],
  "ignorePaths": [
    "node_modules",
    "public",
    "static"
  ]
}

Running cspell

cspell "content/**/*.md"

Expected output on success: No output (exit code 0).

Expected output on failure:

content/api/authentication.md:23:15 - Unknown word (authenticaion)
  Suggestions: authentication, authentications
content/api/authentication.md:89:5 - Unknown word (utilze)
  Suggestions: utilize, useful, utility

Managing Custom Dictionaries

For project-specific terminology, create a dictionary file:

# .dictionary/project-words.txt
DodaTech
DodaZIP
DodaBrowser
Durga
Antivirus
endpoint
middleware
microservice

Update cspell.json to include it:

{
  "dictionaries": ["project-words"],
  "dictionaryDefinitions": [
    {
      "name": "project-words",
      "path": ".dictionary/project-words.txt"
    }
  ]
}

Spell Checking Code in Documentation

Code blocks often contain identifiers, variable names, and commands that are not real words. cspell handles this with ignore patterns:

{
  "ignoreRegExpList": [
    "```[\\s\\S]*?```",
    "`[^`]+`"
  ]
}

This tells cspell to skip text inside code blocks and inline code.

Integrating Spell Check into CI

- name: Spell check
  run: cspell "content/**/*.md"

Or use the cspell action:

- name: Spell check
  uses: streetsidesoftware/cspell-action@v2
  with:
    files: "content/**/*.md"

Common Mistakes

1. Not Adding Technical Terms to the Dictionary

Every new project introduces new terms. Without updating the dictionary, cspell flags valid words on every run, creating noise.

2. Ignoring Spell Check Output

If the CI consistently fails on known terms that are never added to the dictionary, the team starts ignoring spell check failures. Add terms to the dictionary immediately.

3. Spell Checking Without Language Context

A document that mixes English and code identifiers needs different spell checking rules. Use ignore patterns to skip code blocks.

4. Not Running Spell Check Locally

Relying solely on CI for spell checking means writers discover typos only after pushing. Add a local pre-commit hook.

5. Using Only the Default Dictionary

The default English dictionary does not include technical terms, product names, or industry jargon. Customization is essential.

Practice Questions

1. What is the primary purpose of automated spell checking for docs?

Catching typos and misspellings before they reach readers, maintaining professional credibility.

2. How do you add a custom word to cspell's dictionary?

Add it to the words array in cspell.json or to a custom dictionary file referenced in the configuration.

3. Why should you ignore code blocks during spell checking?

Code blocks contain variable names, function names, and identifiers that are not real words but are correct in context.

4. How does spell checking integrate into a CI pipeline?

The spell checker runs as a step in the CI workflow and returns a non-zero exit code when it finds unknown words.

5. Challenge: Create a cspell configuration for a documentation project that includes custom technical terms, ignores code blocks, and runs in a GitHub Actions workflow.

FAQ

{{< faq "How do I add a word for a single run without editing the dictionary?" "Use the --words flag: cspell --words DodaTech content/", >}}

Mini Project

Create a cspell.json configuration for a documentation project with custom technical terms, a project-specific dictionary file, ignore patterns for code blocks, and a GitHub Actions workflow that runs spell checking on every Pull Request.

What's Next

With spell checking automated, learn about Link Checking to ensure all internal and external links in your documentation are valid.