fix: Don't let toc extension append its permalink twice

PR #203: #203

src/mkdocstrings/handlers/base.py

@@ -227,11 +227,14 @@ def update_env(self, md: Markdown, config: dict) -> None:
             config: Configuration options for `mkdocs` and `mkdocstrings`, read from `mkdocs.yml`. See the source code
                 of [mkdocstrings.plugin.MkdocstringsPlugin.on_config][] to see what's in this dictionary.
         """
-        # Re-instantiate md: see https://github.com/tomchristie/mkautodoc/issues/14
-        md = Markdown(
-            extensions=config["mdx"] + [ShiftHeadingsExtension(), PrefixIdsExtension()],
-            extension_configs=config["mdx_configs"],
-        )
+        extensions = config["mdx"] + [ShiftHeadingsExtension(), PrefixIdsExtension()]
+        configs = dict(config["mdx_configs"])
+        # Prevent a bug that happens due to treeprocessors running on the same fragment both as the inner doc and as
+        # part of the re-integrated doc. Namely, the permalink '¶' would be appended twice. This is the only known
+        # non-idempotent effect of an extension, so specifically prevent it on the inner doc.
+        configs.setdefault("toc", {})["permalink"] = False
+
+        md = Markdown(extensions=extensions, extension_configs=configs)
 
         self.env.filters["convert_markdown"] = functools.partial(do_convert_markdown, md)
 
@@ -409,7 +412,7 @@ def run(self, root: Element):  # noqa: WPS231 (not complex)
 class PrefixIdsExtension(Extension):
     """Prepend the configured prefix to IDs of all HTML elements."""
 
-    treeprocessor_priority = 4  # Right after 'toc'.
+    treeprocessor_priority = 4  # Right after 'toc' (needed because that extension adds ids to headers).
 
     def extendMarkdown(self, md: Markdown) -> None:  # noqa: N802 (casing: parent method's name)
         """

tests/test_extension.py

@@ -17,7 +17,7 @@
 def test_render_html_escaped_sequences():
     """Assert HTML-escaped sequences are correctly parsed as XML."""
     config = dict(_DEFAULT_CONFIG)
-    config["mdx"].append(MkdocstringsExtension(config, Handlers(config)))
+    config["mdx"] = [MkdocstringsExtension(config, Handlers(config))]
     md = Markdown(extensions=config["mdx"])
 
     md.convert("::: tests.fixtures.html_escaped_sequences")
@@ -26,7 +26,7 @@ def test_render_html_escaped_sequences():
 def test_multiple_footnotes():
     """Assert footnotes don't get added to subsequent docstrings."""
     config = dict(_DEFAULT_CONFIG, mdx=["footnotes"])
-    config["mdx"].append(MkdocstringsExtension(config, Handlers(config)))
+    config["mdx"] = [MkdocstringsExtension(config, Handlers(config))]
     md = Markdown(extensions=config["mdx"])
 
     output = md.convert(
@@ -52,7 +52,7 @@ def test_multiple_footnotes():
 def test_markdown_heading_level():
     """Assert that Markdown headings' level doesn't exceed heading_level."""
     config = dict(_DEFAULT_CONFIG)
-    config["mdx"].append(MkdocstringsExtension(config, Handlers(config)))
+    config["mdx"] = [MkdocstringsExtension(config, Handlers(config))]
     md = Markdown(extensions=config["mdx"])
 
     output = md.convert("::: tests.fixtures.headings\n    rendering:\n      show_root_heading: true")
@@ -64,9 +64,20 @@ def test_markdown_heading_level():
 def test_reference_inside_autodoc():
     """Assert cross-reference Markdown extension works correctly."""
     config = dict(_DEFAULT_CONFIG)
-    config["mdx"].append(MkdocstringsExtension(config, Handlers(config)))
+    config["mdx"] = [MkdocstringsExtension(config, Handlers(config))]
     md = Markdown(extensions=config["mdx"])
 
     output = md.convert("::: tests.fixtures.cross_reference")
     snippet = 'Link to <span data-mkdocstrings-identifier="something.Else">something.Else</span>.'
     assert snippet in output
+
+
+def test_no_double_toc():
+    """Asserts that the 'toc' extension doesn't apply its modification twice."""
+    config = dict(_DEFAULT_CONFIG)
+    config["mdx_configs"] = {"toc": {"permalink": "@@@"}}
+    config["mdx"] = ["toc", MkdocstringsExtension(config, Handlers(config))]
+    md = Markdown(extensions=config["mdx"], extension_configs=config["mdx_configs"])
+
+    output = md.convert("::: tests.fixtures.headings")
+    assert 3 <= output.count("@@@") < 6