mkdocs-spellcheck

1.2.1 verified Fri May 01 auth: no python

A spell checker plugin for MkDocs that checks spelling in Markdown content. It supports multiple backends (e.g., aspell, hunspell) and allows custom dictionaries. Current version 1.2.1 (2026-02-11), requires Python >=3.10, actively maintained on GitHub by pawamoy.

pip install mkdocs-spellcheck

Common errors

error 'NoneType' object has no attribute 'items' ↓

cause The spellcheck plugin is misconfigured or the known_words key is missing or malformed.

fix

Ensure known_words is a list of strings under the spellcheck plugin block in mkdocs.yml.

error module 'mkdocs_spellcheck' has no attribute 'plugin' ↓

cause Importing from submodules after v1.1.1 when they are deprecated and possibly removed.

fix

Use top-level imports: from mkdocs_spellcheck import SpellCheckPlugin.

error Spellcheck failed: unable to load backend 'hunspell' ↓

cause The hunspell system library is not installed or the Python bindings are missing.

fix

Install system hunspell (e.g., sudo apt install hunspell) and Python bindings (pip install hunspell).

Warnings

breaking Importing from submodules (e.g., `from mkdocs_spellcheck.plugin import SpellCheckPlugin`) is deprecated since v1.1.1 and will be removed in a future release. Always import from the top-level `mkdocs_spellcheck`. ↓

fix Use `from mkdocs_spellcheck import SpellCheckPlugin` instead.

gotcha Plugin initialization may fail if `search` plugin is not listed before `spellcheck` in the plugins list. The order matters in MkDocs. ↓

fix Place `search` before `spellcheck` in mkdocs.yml plugins list.

gotcha Backends like hunspell or aspell must be installed on the system separately; the Python package only provides bindings. If no backend is available, the plugin will skip spellchecking silently unless misconfigured. ↓

fix Install system package (e.g., `sudo apt install hunspell`) and ensure Python bindings are installed (e.g., `pip install hunspell`).

deprecated The `aspell` backend is no longer actively supported and may be removed in a future version. It is recommended to use `hunspell` instead. ↓

fix Switch to hunspell backend.

Install

pip install mkdocs-spellcheck[hunspell]

pip install mkdocs-spellcheck[aspell]

Imports

SpellCheckPlugin

wrong

from mkdocs_spellcheck.plugin import SpellCheckPlugin

correct

from mkdocs_spellcheck import SpellCheckPlugin

Submodule imports deprecated since 1.1.1

config

wrong

from mkdocs_spellcheck.config import config

correct

from mkdocs_spellcheck import config

Top-level imports are preferred; submodules deprecated

Quickstart

Enable the spellcheck plugin in your MkDocs configuration. Add known words to avoid false positives. The search plugin must be listed before spellcheck for compatibility.

# mkdocs.yml
plugins:
  - search
  - spellcheck:
      known_words:
        - mkdocs
        - spellcheck
      backends:
        - hunspell
      # Optional: ignore code blocks
      ignore_code: true