Skip to content

plugin ¤

MkDocs SpellCheck package.

A spell checker plugin for MkDocs.

Classes:

Name Description
SpellCheckPlugin

A mkdocs plugin.

Functions:

Name Description
load_backend

Load the specified backend.

SpellCheckPlugin() ¤

Bases: BasePlugin

A mkdocs plugin.

This plugin defines the following event hooks:

  • on_config
  • on_page_content

Check the Developing Plugins page of mkdocs for more information about its plugin system.

Methods:

Name Description
on_config

Load words to ignore.
on_page_content

Spell check everything.
Source code in src/mkdocs_spellcheck/plugin.py 
76
77
78
def __init__(self) -> None:  # noqa: D107
    self.known_words: set[str] = set()
    super().__init__()

on_config(config: MkDocsConfig) -> MkDocsConfig | None ¤

Load words to ignore.

Hook for the on_config event.

Parameters:

Name Type Description Default
config MkDocsConfig

The MkDocs config object.

 required

Returns:

Type Description
MkDocsConfig | None

The modified config.
Source code in src/mkdocs_spellcheck/plugin.py 
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
    """Load words to ignore.

    Hook for the [`on_config` event](https://www.mkdocs.org/user-guide/plugins/#on_config).

    Arguments:
        config: The MkDocs config object.

    Returns:
        The modified config.
    """
    self.strict_only = self.config["strict_only"]
    self.backends_config = self.config["backends"]
    self.skip_files = self.config["skip_files"]
    self.min_length = self.config["min_length"]
    self.max_capital = self.config["max_capital"]
    self.ignore_code = self.config["ignore_code"]
    self.allow_unicode = self.config["allow_unicode"]
    self.run = config["strict"] or not self.strict_only

    if not self.run:
        return config

    known_words = self.config["known_words"]
    if isinstance(known_words, str):
        self.known_words |= set(Path(config["docs_dir"], known_words).read_text().splitlines())
    else:
        self.known_words |= set(known_words)

    self.backends = {}
    for backend_conf in self.backends_config:
        if isinstance(backend_conf, str):
            backend_name = backend_conf
            backend_config = {}
        else:
            backend_name, backend_config = next(iter(backend_conf.items()))
        self.backends[backend_name] = load_backend(backend_name)(
            known_words=self.known_words,
            config=backend_config,
        )

    return config

on_page_content(html: str, page: Page, **kwargs: Any) -> None ¤

Spell check everything.

Hook for the on_page_content event.

Parameters:

Name Type Description Default
html str

The HTML text.

 required
page Page

The page instance.

 required
**kwargs Any

Additional arguments passed by MkDocs.

 {}
Source code in src/mkdocs_spellcheck/plugin.py 
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
def on_page_content(self, html: str, page: Page, **kwargs: Any) -> None:  # noqa: ARG002
    """Spell check everything.

    Hook for the [`on_page_content` event](https://www.mkdocs.org/user-guide/plugins/#on_page_content).

    Arguments:
        html: The HTML text.
        page: The page instance.
        **kwargs: Additional arguments passed by MkDocs.
    """
    if self.run and not any(fnmatch(page.file.src_path, pattern) for pattern in self.skip_files):
        words = get_words(
            html,
            known_words=self.known_words,
            min_length=self.min_length,
            max_capital=self.max_capital,
            ignore_code=self.ignore_code,
            allow_unicode=self.allow_unicode,
        )
        for word in words:
            for backend in self.backends.values():
                backend.check(page, word)

load_backend(name: str) -> type[Backend] ¤

Load the specified backend.

This function imports the specified backend and returns its class. It is important not to import the backends at the top level, as they may not be installed.

Parameters:

Name Type Description Default
name str

The name of the backend to load.

 required

Returns:

Type Description
type[Backend]

The backend class.
Source code in src/mkdocs_spellcheck/plugin.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
def load_backend(name: str) -> type[Backend]:
    """Load the specified backend.

    This function imports the specified backend and returns its class.
    It is important not to import the backends at the top level, as
    they may not be installed.

    Arguments:
        name: The name of the backend to load.

    Returns:
        The backend class.
    """
    if name == "symspellpy":
        from mkdocs_spellcheck.backends import symspellpy

        return symspellpy.SymspellpyBackend

    if name == "codespell":
        from mkdocs_spellcheck.backends import codespell

        return codespell.CodespellBackend

    raise ValueError(f"Unknown backend: {name}")