Update Extension API documentation

waylan · web-flow · commit 8453df010daf · 2026-07-08T14:19:23.000-04:00
* Document the priorities assigned by each extension for the API Reference.

* Link Extension API docs to API Reference.

    Various sections were reduced to avoid repetition with the API Reference.
    Other sections were expanded to provide more links. A deeper explanation
    of the registry priority has been added. 

Fixes 1612.
diff --git a/.spell-dict b/.spell-dict
@@ -80,6 +80,7 @@ namespace
 NanoDOM
 Neale
 nosetests
+noqa
 OrderedDict
 OrderedDicts
 OSX
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -16,6 +16,7 @@ See the [Contributing Guide](contributing.md) for details.
 
 * Fix `SetextHeaderProcessor` regex to prevent mixed `=` and `-` chars in setext-style headers (#1606).
 * Officially document all included extensions as being in maintenance mode.
+* Link the Extension API documentation to the API Reference (#1612).
 
 ## [3.10.2] - 2026-02-09
 
diff --git a/docs/extensions/api.md b/docs/extensions/api.md
diff --git a/markdown/extensions/abbr.py b/markdown/extensions/abbr.py
@@ -69,7 +69,16 @@ def load_glossary(self, dictionary: dict[str, str]):
             self.glossary = {**dictionary, **self.glossary}
 
     def extendMarkdown(self, md):
-        """ Insert `AbbrTreeprocessor` and `AbbrBlockprocessor`. """
+        """
+        Register the processors.
+
+        | Class Instance                                                      | Registry                                                         | Name   | Priority |
+        | ------------------------------------------------------------------- | ---------------------------------------------------------------- | ------ | :------: |
+        | [`AbbrTreeprocessor`][markdown.extensions.abbr.AbbrTreeprocessor]   | [`treeprocessors`][markdown.treeprocessors.build_treeprocessors] | `abbr` | `7`      |
+        | [`AbbrBlockprocessor`][markdown.extensions.abbr.AbbrBlockprocessor] | [`blockprocessors`][markdown.blockprocessors.build_block_parser] | `abbr` | `16`     |
+
+        """
+        # flake8: noqa: E501 75-78
         if (self.config['glossary'][0]):
             self.load_glossary(self.config['glossary'][0])
         self.abbrs.update(self.glossary)
diff --git a/markdown/extensions/admonition.py b/markdown/extensions/admonition.py
@@ -41,7 +41,15 @@ class AdmonitionExtension(Extension):
     """ Admonition extension for Python-Markdown. """
 
     def extendMarkdown(self, md):
-        """ Add Admonition to Markdown instance. """
+        """
+        Register the processor.
+
+        | Class Instance                                                              | Registry                                                         | Name   | Priority |
+        | --------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------ | :------: |
+        | [`AdmonitionProcessor`][markdown.extensions.admonition.AdmonitionProcessor] | [`blockprocessors`][markdown.blockprocessors.build_block_parser] | `admonition` | `105` |
+
+        """
+        # flake8: noqa: E501 47-49
         md.registerExtension(self)
 
         md.parser.blockprocessors.register(AdmonitionProcessor(md.parser), 'admonition', 105)
diff --git a/markdown/extensions/attr_list.py b/markdown/extensions/attr_list.py
@@ -196,6 +196,15 @@ def sanitize_name(self, name: str) -> str:
 class AttrListExtension(Extension):
     """ Attribute List extension for Python-Markdown """
     def extendMarkdown(self, md):
+        """
+        Register the processor.
+
+        | Class Instance                                                              | Registry                                                         | Name   | Priority |
+        | --------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------ | :------: |
+        | [`AttrListTreeprocessor`][markdown.extensions.attr_list.AttrListTreeprocessor] | [`treeprocessors`][markdown.treeprocessors.build_treeprocessors] | `attr_list` | `8` |
+
+        """
+        # flake8: noqa: E501 202-204
         md.treeprocessors.register(AttrListTreeprocessor(md), 'attr_list', 8)
         md.registerExtension(self)
 
diff --git a/markdown/extensions/codehilite.py b/markdown/extensions/codehilite.py
@@ -335,7 +335,15 @@ def __init__(self, **kwargs):
                 self.config[key] = [value, '']
 
     def extendMarkdown(self, md):
-        """ Add `HilitePostprocessor` to Markdown instance. """
+        """
+        Register the processor.
+
+        | Class Instance                                                              | Registry                                                         | Name   | Priority |
+        | --------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------ | :------: |
+        | [`HiliteTreeprocessor`][markdown.extensions.codehilite.HiliteTreeprocessor] | [`treeprocessors`][markdown.treeprocessors.build_treeprocessors] | `hilite` | `30` |
+
+        """
+        # flake8: noqa: E501 341-343
         hiliter = HiliteTreeprocessor(md)
         hiliter.config = self.getConfigs()
         md.treeprocessors.register(hiliter, 'hilite', 30)
diff --git a/markdown/extensions/def_list.py b/markdown/extensions/def_list.py
@@ -110,7 +110,16 @@ class DefListExtension(Extension):
     """ Add definition lists to Markdown. """
 
     def extendMarkdown(self, md):
-        """ Add an instance of `DefListProcessor` to `BlockParser`. """
+        """
+        Register the processors.
+
+        | Class Instance                                                              | Registry                                                         | Name   | Priority |
+        | --------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------ | :------: |
+        | [`DefListIndentProcessor`][markdown.extensions.def_list.DefListIndentProcessor] | [`blockprocessors`][markdown.blockprocessors.build_block_parser] | `defindent` | `85` |
+        | [`DefListProcessor`][markdown.extensions.def_list.DefListProcessor] | [`blockprocessors`][markdown.blockprocessors.build_block_parser] | `deflist` | `25` |
+
+        """
+        # flake8: noqa: E501 116-119
         md.parser.blockprocessors.register(DefListIndentProcessor(md.parser), 'defindent', 85)
         md.parser.blockprocessors.register(DefListProcessor(md.parser), 'deflist', 25)
 
diff --git a/markdown/extensions/fenced_code.py b/markdown/extensions/fenced_code.py
@@ -44,7 +44,15 @@ def __init__(self, **kwargs):
         super().__init__(**kwargs)
 
     def extendMarkdown(self, md):
-        """ Add `FencedBlockPreprocessor` to the Markdown instance. """
+        """
+        Register the processor.
+
+        | Class Instance                                                              | Registry                                                         | Name   | Priority |
+        | --------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------ | :------: |
+        | [`FencedBlockPreprocessor`][markdown.extensions.fenced_code.FencedBlockPreprocessor] | [`blockprocessors`][markdown.blockprocessors.build_block_parser] | `fenced_code_block` | `25` |
+
+        """
+        # flake8: noqa: E501 50-52
         md.registerExtension(self)
 
         md.preprocessors.register(FencedBlockPreprocessor(md, self.getConfigs()), 'fenced_code_block', 25)
diff --git a/markdown/extensions/footnotes.py b/markdown/extensions/footnotes.py
@@ -83,7 +83,19 @@ def __init__(self, **kwargs):
         self.reset()
 
     def extendMarkdown(self, md):
-        """ Add pieces to Markdown. """
+        """ Register the processors.
+
+        | Class Instance                                                              | Registry                                                         | Name   | Priority |
+        | --------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------ | :------: |
+        | [`FootnoteBlockProcessor`][markdown.extensions.footnotes.FootnoteBlockProcessor] | [`blockprocessors`][markdown.blockprocessors.build_block_parser] | `footnote` | `17` |
+        | [`FootnoteInlineProcessor`][markdown.extensions.footnotes.FootnoteInlineProcessor] | [`inlinepatterns`][markdown.inlinepatterns.build_inlinepatterns] | `footnote` | `175` |
+        | [`FootnoteTreeprocessor`][markdown.extensions.footnotes.FootnoteTreeprocessor] | [`treeprocessors`][markdown.treeprocessors.build_treeprocessors] | `footnote` | `50` |
+        | [`FootnoteReorderingProcessor`][markdown.extensions.footnotes.FootnoteReorderingProcessor] | [`treeprocessors`][markdown.treeprocessors.build_treeprocessors] | `footnote-reorder` | `19` |
+        | [`FootnotePostTreeprocessor`][markdown.extensions.footnotes.FootnotePostTreeprocessor] | [`treeprocessors`][markdown.treeprocessors.build_treeprocessors] | `footnote-duplicate` | `15` |
+        | [`FootnotePostprocessor`][markdown.extensions.footnotes.FootnotePostprocessor] | [`postprocessors`][markdown.postprocessors.build_postprocessors] | `footnote` | `25` |
+
+        """
+        # flake8: noqa: E501 88-95
         md.registerExtension(self)
         self.parser = md.parser
         self.md = md
diff --git a/markdown/extensions/legacy_attrs.py b/markdown/extensions/legacy_attrs.py
@@ -63,7 +63,14 @@ def attributeCallback(match: re.Match[str]):
 
 class LegacyAttrExtension(Extension):
     def extendMarkdown(self, md):
-        """ Add `LegacyAttrs` to Markdown instance. """
+        """ Register the processor.
+
+        | Class Instance                                                | Registry                                                         | Name   | Priority |
+        | ------------------------------------------------------------- | ---------------------------------------------------------------- | ------ | :------: |
+        | [`LegacyAttrs`][markdown.extensions.legacy_attrs.LegacyAttrs] | [`treeprocessors`][markdown.treeprocessors.build_treeprocessors] | `legacyattrs` | `15` |
+
+        """
+        # flake8: noqa: E501 68-70
         md.treeprocessors.register(LegacyAttrs(md), 'legacyattrs', 15)
 
 
diff --git a/markdown/extensions/legacy_em.py b/markdown/extensions/legacy_em.py
@@ -43,7 +43,14 @@ class LegacyEmExtension(Extension):
     """ Add legacy_em extension to Markdown class."""
 
     def extendMarkdown(self, md):
-        """ Modify inline patterns. """
+        """ Register the processor.
+
+        | Class Instance                                                | Registry                                                         | Name   | Priority |
+        | ------------------------------------------------------------- | ---------------------------------------------------------------- | ------ | :------: |
+        | [`LegacyUnderscoreProcessor`][markdown.extensions.legacy_em.LegacyUnderscoreProcessor] | [`inlinepatterns`][markdown.inlinepatterns.build_inlinepatterns] | `em_strong2` | `50` |
+
+        """
+        # flake8: noqa: E501 48-50
         md.inlinePatterns.register(LegacyUnderscoreProcessor(r'_'), 'em_strong2', 50)
 
 
diff --git a/markdown/extensions/md_in_html.py b/markdown/extensions/md_in_html.py
@@ -424,8 +424,16 @@ class MarkdownInHtmlExtension(Extension):
     """Add Markdown parsing in HTML to Markdown class."""
 
     def extendMarkdown(self, md):
-        """ Register extension instances. """
+        """ Register the processors.
 
+        | Class Instance                                                              | Registry                                                         | Name   | Priority |
+        | --------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------ | :------: |
+        | [`HtmlBlockPreprocessor`][markdown.extensions.md_in_html.HtmlBlockPreprocessor] | [`preprocessors`][markdown.preprocessors.build_preprocessors] | `html_block` | `20` |
+        | [`MarkdownInHtmlProcessor`][markdown.extensions.md_in_html.MarkdownInHtmlProcessor] | [`blockprocessors`][markdown.blockprocessors.build_block_parser] | `markdown_block` | `105` |
+        | [`MarkdownInHTMLPostprocessor`][markdown.extensions.md_in_html.MarkdownInHTMLPostprocessor] | [`postprocessors`][markdown.postprocessors.build_postprocessors] | `raw_html` | `30` |
+
+        """
+        # flake8: noqa: E501 429-433
         # Replace raw HTML preprocessor
         md.preprocessors.register(HtmlBlockPreprocessor(md), 'html_block', 20)
         # Add `blockprocessor` which handles the placeholders for `etree` elements
diff --git a/markdown/extensions/meta.py b/markdown/extensions/meta.py
@@ -40,7 +40,14 @@ class MetaExtension (Extension):
     """ Meta-Data extension for Python-Markdown. """
 
     def extendMarkdown(self, md):
-        """ Add `MetaPreprocessor` to Markdown instance. """
+        """ Register the processor.
+
+        | Class Instance                                                  | Registry                                                      | Name   | Priority |
+        | --------------------------------------------------------------- | ------------------------------------------------------------- | ------ | :------: |
+        | [`MetaPreprocessor`][markdown.extensions.meta.MetaPreprocessor] | [`preprocessors`][markdown.preprocessors.build_preprocessors] | `meta` | `27` |
+
+        """
+        # flake8: noqa: E501 45-47
         md.registerExtension(self)
         self.md = md
         md.preprocessors.register(MetaPreprocessor(md), 'meta', 27)
diff --git a/markdown/extensions/nl2br.py b/markdown/extensions/nl2br.py
@@ -30,9 +30,17 @@
 
 
 class Nl2BrExtension(Extension):
+    """ Newline-to-break extension for Python-Markdown. """
 
     def extendMarkdown(self, md):
-        """ Add a `SubstituteTagInlineProcessor` to Markdown. """
+        """ Register the processor.
+
+        | Class Instance                                                  | Registry                                                      | Name   | Priority |
+        | --------------------------------------------------------------- | ------------------------------------------------------------- | ------ | :------: |
+        | [`SubstituteTagInlineProcessor`][markdown.inlinepatterns.SubstituteTagInlineProcessor] | [`inlinepatterns`][markdown.inlinepatterns.build_inlinepatterns] | `nl` | `5` |
+
+        """
+        # flake8: noqa: E501 38-40
         br_tag = SubstituteTagInlineProcessor(BR_RE, 'br')
         md.inlinePatterns.register(br_tag, 'nl', 5)
 
diff --git a/markdown/extensions/sane_lists.py b/markdown/extensions/sane_lists.py
@@ -60,7 +60,15 @@ class SaneListExtension(Extension):
     """ Add sane lists to Markdown. """
 
     def extendMarkdown(self, md):
-        """ Override existing Processors. """
+        """ Register the processors.
+
+        | Class Instance                                                            | Registry                                                         | Name   | Priority |
+        | ------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------ | :------: |
+        | [`SaneOListProcessor`][markdown.extensions.sane_lists.SaneOListProcessor] | [`blockprocessors`][markdown.blockprocessors.build_block_parser] | `olist` | `40` |
+        | [`SaneUListProcessor`][markdown.extensions.sane_lists.SaneUListProcessor] | [`blockprocessors`][markdown.blockprocessors.build_block_parser] | `ulist` | `30` |
+
+        """
+        # flake8: noqa: E501 65-68
         md.parser.blockprocessors.register(SaneOListProcessor(md.parser), 'olist', 40)
         md.parser.blockprocessors.register(SaneUListProcessor(md.parser), 'ulist', 30)
 
diff --git a/markdown/extensions/smarty.py b/markdown/extensions/smarty.py
@@ -257,6 +257,21 @@ def educateQuotes(self, md: Markdown) -> None:
         self._addPatterns(md, patterns, 'quotes', 30)
 
     def extendMarkdown(self, md):
+        """ Register the processors.
+
+        | Class Instance                                                              | Registry                                                         | Name   | Priority |
+        | --------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------ | :------: |
+        | [`markdown.treeprocessors.InlineProcessor`][markdown.treeprocessors.InlineProcessor] | [`treeprocessors`][markdown.treeprocessors.build_treeprocessors] | `smarty` | `6` |
+        | [`markdown.inlinepatterns.HtmlInlineProcessor`][markdown.inlinepatterns.HtmlInlineProcessor] | [`inlinepatterns`][markdown.inlinepatterns.build_inlinepatterns] | `html` | `90` |
+
+        The `HtmlInlineProcessor` , above, is only used if the `smart_angled_quotes` option is enabled.
+
+        The `InlineProcessor`, above, is a separate instance from the `InlineProcessor` used for
+        standard inline parsing. It contains a collection of inline patterns dependent upon the
+        various configuration options.
+
+        """
+        # flake8: noqa: E501 263-265
         configs = self.getConfigs()
         self.inlinePatterns: Registry[inlinepatterns.InlineProcessor] = Registry()
         if configs['smart_ellipses']:
diff --git a/markdown/extensions/tables.py b/markdown/extensions/tables.py
@@ -237,7 +237,14 @@ def __init__(self, **kwargs):
         super().__init__(**kwargs)
 
     def extendMarkdown(self, md):
-        """ Add an instance of `TableProcessor` to `BlockParser`. """
+        """ Register the processor.
+
+        | Class Instance                                                | Registry                                                         | Name   | Priority |
+        | ------------------------------------------------------------- | ---------------------------------------------------------------- | ------ | :------: |
+        | [`TableProcessor`][markdown.extensions.tables.TableProcessor] | [`blockprocessors`][markdown.blockprocessors.build_block_parser] | `table` | `75` |
+
+        """
+        # flake8: noqa: E501 242-244
         if '|' not in md.ESCAPED_CHARS:
             md.ESCAPED_CHARS.append('|')
         processor = TableProcessor(md.parser, self.getConfigs())
diff --git a/markdown/extensions/toc.py b/markdown/extensions/toc.py
@@ -416,6 +416,7 @@ def run(self, doc: etree.Element) -> None:
 
 
 class TocExtension(Extension):
+    """ Table of Contents Extension to Python-Markdown. """
 
     TreeProcessorClass = TocTreeprocessor
 
@@ -472,7 +473,14 @@ def __init__(self, **kwargs):
         super().__init__(**kwargs)
 
     def extendMarkdown(self, md):
-        """ Add TOC tree processor to Markdown. """
+        """ Register the processor.
+
+        | Class Instance                                                 | Registry                                                         | Name   | Priority |
+        | -------------------------------------------------------------- | ---------------------------------------------------------------- | ------ | :------: |
+        | [`TocTreeprocessor`][markdown.extensions.toc.TocTreeprocessor] | [`treeprocessors`][markdown.treeprocessors.build_treeprocessors] | `toc` | `5` |
+
+        """
+        # flake8: noqa: E501 478-480
         md.registerExtension(self)
         self.md = md
         self.reset()
diff --git a/markdown/extensions/wikilinks.py b/markdown/extensions/wikilinks.py
@@ -48,6 +48,14 @@ def __init__(self, **kwargs):
         super().__init__(**kwargs)
 
     def extendMarkdown(self, md):
+        """ Register the processor.
+
+        | Class Instance                                                              | Registry                                                         | Name   | Priority |
+        | --------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------ | :------: |
+        | [`WikiLinksInlineProcessor`][markdown.extensions.wikilinks.WikiLinksInlineProcessor] | [`inlinepatterns`][markdown.inlinepatterns.build_inlinepatterns] | `wikilink` | `75` |
+
+        """
+        # flake8: noqa: E501 53-55
         self.md = md
 
         # append to end of inline patterns
diff --git a/markdown/util.py b/markdown/util.py
@@ -376,6 +376,10 @@ def register(self, item: _T, name: str, priority: float) -> None:
         old item is lost with no way to recover it. The new item will be
         sorted according to its priority and will **not** retain the position
         of the old item.
+
+        Items assigned a higher number are given a higher priority. In other
+        words, items assigned a higher number are sorted to be before those
+        assigned a lower number.
         """
         if name in self:
             # Remove existing item of same name first
