mkdocs-spellcheck

What it is and what it does

mkdocs-spellcheck is a MkDocs plugin that runs spell-checking on your final built HTML documentation. It integrates with your build pipeline and can use either codespell or symspellpy as its checking backend, each with different dictionary options and tuning parameters. You configure it in mkdocs.yml to specify which backend(s) to use, custom word lists, code-block handling, and file exclusions, then invoke it during the build step with mkdocs build -s.

The plugin is designed to catch typos and spelling errors before documentation is published. It supports granular configuration—minimum word length, capital-letter thresholds, Unicode handling, and on-off regions in Markdown to skip checking in specific blocks. The project is currently in maintenance mode, meaning bug fixes and security updates may be limited, though the codebase is stable and supports modern Python versions (3.10 through 3.14).

Use it for:

• Catch spelling errors in technical documentation before publishing to ensure professionalism.
• Enforce consistent spelling conventions across large documentation sites using custom dictionaries.
• Integrate spell checking into CI/CD pipelines to fail builds when typos are detected.
• Exclude code snippets and proper names from spell checking while validating prose.
• Temporarily disable spell checking for specific sections using on-off comment guards.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A spell checker plugin for MkDocs that validates spelling in generated HTML pages using pluggable backends like codespell or symspellpy.

Yes, if you maintain MkDocs documentation and want automated spell checking. The plugin is low-friction to install, permissively licensed, and works with modern Python. However, the aging maintenance status and explicit statement that the maintainer is dedicating effort elsewhere means you should be prepared to fork or switch if critical issues arise. For new projects or teams with active documentation workflows, it's a solid choice; for mission-critical systems, monitor the project's activity.

Install

mkdocs-spellcheck on PyPI

pip install mkdocs-spellcheck

uv add mkdocs-spellcheck

poetry add mkdocs-spellcheck

Installing mkdocs-spellcheck

Before you install

Low friction: pure Python wheel with a single runtime dependency on mkdocs. Maintenance status is aging—last release was 184 days ago and the maintainer has explicitly stated the project is in maintenance mode, dedicating effort elsewhere.

License in practice

ISC license is permissive and imposes minimal restrictions; you can use, modify, and distribute the package freely with minimal legal friction.

Quickstart

pip install 'mkdocs-spellcheck[all]'

# In mkdocs.yml:
plugins:
  - spellcheck:
      backends:
        - symspellpy
        - codespell:
            dictionaries: [clear, rare]
      known_words: known_words.txt
      ignore_code: yes

# Then run:
mkdocs build -s

Requires Python 3.10 or later; one of the optional backends (codespell or symspellpy) must be installed via extras.

Verify before relying

• Whether the aging maintenance status poses a risk for future Python or mkdocs compatibility issues.
• How well the plugin performs on large documentation sites or whether there are known performance bottlenecks.
• Whether the two backends (codespell and symspellpy) have materially different accuracy or speed characteristics.

Package facts

Evidence: mkdocs_spellcheck-1.2.1-py3-none-any.whl

Tags

More Software Development packages