mkdocs_spellcheck ¤

Bases: ABC

Abstract class for spelling backends.

Parameters:

• config ¤

  (dict[str, Any]) –

  User configuration from mkdocs.yml.

• known_words ¤

  (set[str] | None, default: None ) –

  Globally known words.

Methods:

• check –

  Check a word appearing in a page.

33
34
35
36
37
38
39
40
41

@abstractmethod
def __init__(self, config: dict[str, Any], known_words: set[str] | None = None) -> None:
    """Initialize the backend.

    Parameters:
        config: User configuration from `mkdocs.yml`.
        known_words: Globally known words.
    """
    raise NotImplementedError

check(page: Page, word: str) -> None

43
44
45
46
47
48
49
50
51

@abstractmethod
def check(self, page: Page, word: str) -> None:
    """Check a word appearing in a page.

    Parameters:
        page: The MkDocs page the word appears in.
        word: The word to check.
    """
    raise NotImplementedError

Bases: Backend

Backend for the codespell tool.

This backend needs to build a list of misspellings based on dictionaries provided by codespell itself.

Parameters:

• config ¤

  (dict[str, Any]) –

  User configuration from mkdocs.yml.

• known_words ¤

  (set[str] | None, default: None ) –

  Globally known words.

Methods:

• check –

  Check a word against the codespell misspellings.

Attributes:

• misspellings (dict[str, Misspelling]) –

  A mapping of misspelled words to their corrections.

70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

def __init__(self, config: dict[str, Any], known_words: set[str] | None = None) -> None:
    """Initialize the `codespell` backend.

    This backend needs to build a list of misspellings based
    on dictionaries provided by `codespell` itself.

    Parameters:
        config: User configuration from `mkdocs.yml`.
        known_words: Globally known words.
    """
    known_words = known_words or set()
    use_dictionaries = []
    for dictionary in config.get("dictionaries", _DEFAULT_DICTS):
        for builtin in _builtin_dictionaries:
            if builtin[0] == dictionary:
                use_dictionaries.append(os.path.join(_data_root, f"dictionary{builtin[2]}.txt"))  # noqa: PERF401,PTH118

    self.misspellings: dict[str, Misspelling] = {}
    """A mapping of misspelled words to their corrections."""

    for dictionary in use_dictionaries:
        build_dict(dictionary, self.misspellings, known_words)

misspellings: dict[str, Misspelling] = {}

check(page: Page, word: str) -> None

93
94
95
96
97
98

def check(self, page: Page, word: str) -> None:
    """Check a word against the `codespell` misspellings."""
    if word in self.misspellings:
        # reason = self.misspellings[word].reason
        fixword = fix_case(word, self.misspellings[word].data)
        _logger.warning(f"(codespell) {page.file.src_path}: Misspelled '{word}', did you mean '{fixword}'?")

Bases: BasePlugin[_SpellCheckConfig]

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:

• on_config –

  Load words to ignore.

• on_page_content –

  Spell check everything.

Attributes:

• allow_unicode (bool) –

  Keep unicode characters.

• backends_config (list[str | dict[str, Any]]) –

  Backend configuration.

• ignore_code (bool) –

  Ignore words in code blocks.

• known_words (set[str]) –

  Words to ignore.

• max_capital (int) –

  Maximum number of capital letters in a word to consider it.

• min_length (int) –

  Minimum word length.

• run (bool) –

  Whether to run the plugin.

• skip_files (list[str]) –

  Files to skip.

• strict_only (bool) –

  Only run in strict mode.

111
112
113
114

def __init__(self) -> None:
    self.known_words: set[str] = set()
    """Words to ignore."""
    super().__init__()

allow_unicode: bool

backends_config: list[str | dict[str, Any]]

ignore_code: bool

known_words: set[str] = set()

max_capital: int

min_length: int

run: bool

skip_files: list[str]

strict_only: bool

on_config(config: MkDocsConfig) -> MkDocsConfig | None

116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157

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: dict[str, Any] = {}
        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

159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180

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)

Bases: Backend

Backend for the symspellpy library.

This backend needs to load dictionaries provided by symspellpy itself.

Parameters:

• config ¤

  (dict[str, Any]) –

  User configuration from mkdocs.yml.

• known_words ¤

  (set[str] | None, default: None ) –

  Globally known words.

Methods:

• check –

  Check a word against the symspellpy dictionary.

Attributes:

• spell –

  The symspellpy spell checker.

63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

def __init__(self, config: dict[str, Any], known_words: set[str] | None = None) -> None:  # noqa: ARG002
    """Initialize the `symspellpy` backend.

    This backend needs to load dictionaries provided
    by `symspellpy` itself.

    Parameters:
        config: User configuration from `mkdocs.yml`.
        known_words: Globally known words.
    """
    self.spell = SymSpell()
    """The `symspellpy` spell checker."""
    dictionary_res = resources.files("symspellpy").joinpath("frequency_dictionary_en_82_765.txt")
    with resources.as_file(dictionary_res) as dictionary_path:
        self.spell.load_dictionary(dictionary_path, 0, 1)

spell = SymSpell()

check(page: Page, word: str) -> None

79
80
81
82
83
84
85
86
87
88
89

def check(self, page: Page, word: str) -> None:
    """Check a word against the `symspellpy` dictionary."""
    suggestions = self.spell.lookup(word, Verbosity.CLOSEST, max_edit_distance=2)
    if suggestions:
        candidates = "', '".join(suggestion.term for suggestion in suggestions if suggestion.term != word)
        if candidates:
            _logger.warning(
                f"(symspellpy) {page.file.src_path}: Misspelled '{word}', did you mean '{candidates}'?",
            )
    else:
        _logger.warning(f"(symspellpy) {page.file.src_path}: Misspelled '{word}', no suggestions")