feat: render HTML for Cross References

mdformat_mkdocs/_normalize_list.py

@@ -313,7 +313,7 @@ class SemanticIndent(Enum):
 
 def parse_semantic_indent(last: SemanticIndent, line: LineResult) -> SemanticIndent:
     """Conditionally evaluate when semantic indents are necessary."""
-    # TODO: This works, but is very confusing
+    # PLANNED: This works, but is very confusing
     if not line.parsed.content:
         result = SemanticIndent.EMPTY
 
@@ -375,8 +375,6 @@ def normalize_list(
     check_if_align_semantic_breaks_in_lists: Callable[[], bool],  # Attach with partial
 ) -> str:
     """Format markdown list."""
-    # FIXME: Is this filter working correctly?
-    #   If it is, the test for "Formats non-root lists" should be failing
     if node.level > 1:
         # Note: this function is called recursively,
         #   so only process the top-level item

mdformat_mkdocs/mdit_plugins/_mkdocstrings_autorefs.py

@@ -29,9 +29,9 @@ def _mkdocstrings_autorefs_plugin(state: StateInline, silent: bool) -> bool:
         return True
 
     anchor = match["anchor"]
-    with new_token(state, MKDOCSTRINGS_AUTOREFS_PREFIX, "a") as open_t:
-        open_t.attrs = {"id": anchor, "href": ""}
-        open_t.meta = {"content": f"[](){{#{anchor}}}"}
+    with new_token(state, MKDOCSTRINGS_AUTOREFS_PREFIX, "a") as token:
+        token.attrs = {"id": anchor, "href": ""}
+        token.meta = {"content": f"[](){{#{anchor}}}"}
 
     state.pos += match.end()
 

mdformat_mkdocs/mdit_plugins/_mkdocstrings_crossreference.py

@@ -15,22 +15,34 @@
 
 from markdown_it import MarkdownIt
 from markdown_it.rules_inline import StateInline
+from mdformat_admon.factories import new_token
 
-LINK_PATTERN = re.compile(r"\[([^[|\]\n]+)\]\[([^\]\n]*)\]")
+_CROSSREFERENCE_PATTERN = re.compile(r"\[(?P<link>[^[|\]\n]+)\]\[(?P<href>[^\]\n]*)\]")
 MKDOCSTRINGS_CROSSREFERENCE_PREFIX = "mkdocstrings_crossreference"
 
 
 def _mkdocstrings_crossreference(state: StateInline, silent: bool) -> bool:
-    match = LINK_PATTERN.match(state.src[state.pos :])
+    match = _CROSSREFERENCE_PATTERN.match(state.src[state.pos : state.posMax])
     if not match:
         return False
 
     if silent:
         return True
 
-    token = state.push(MKDOCSTRINGS_CROSSREFERENCE_PREFIX, "", 0)
-    token.content = match.group()
+    original_pos = state.pos
+    original_pos_max = state.posMax
+    state.pos += 1
+    state.posMax = state.pos + len(match["link"])
+    with new_token(state, MKDOCSTRINGS_CROSSREFERENCE_PREFIX, "a") as token:
+        token.attrs = {"href": f'#{match["href"] or match["link"]}'}
+        token.meta = {"content": match.group()}
 
+        state.linkLevel += 1
+        state.md.inline.tokenize(state)
+        state.linkLevel -= 1
+
+    state.pos = original_pos
+    state.posMax = original_pos_max
     state.pos += match.end()
 
     return True

mdformat_mkdocs/plugin.py

@@ -85,8 +85,8 @@ def _render_meta_content(node: RenderTreeNode, context: RenderContext) -> str:
     return node.meta.get("content", "")
 
 
-def _render_pymd_abbr(node: RenderTreeNode, context: RenderContext) -> str:  # noqa: ARG001
-    """Render an Abbreviation."""
+def _render_inline_content(node: RenderTreeNode, context: RenderContext) -> str:  # noqa: ARG001
+    """Render the node's inline content."""
     [inline] = node.children
     return inline.content
 
@@ -111,7 +111,7 @@ def _render_with_default_renderer(
 def _render_cross_reference(node: RenderTreeNode, context: RenderContext) -> str:
     """Render a MkDocs crossreference link."""
     if _IGNORE_MISSING_REFERENCES:
-        return _render_node_content(node, context)
+        return _render_meta_content(node, context)
     # Default to treating the matched content as a link
     return _render_with_default_renderer(node, context, "link")
 
@@ -126,7 +126,7 @@ def _render_cross_reference(node: RenderTreeNode, context: RenderContext) -> str
     "content_tab_mkdocs_title": ADMON_RENDERS["admonition_title"],
     MKDOCSTRINGS_CROSSREFERENCE_PREFIX: _render_cross_reference,
     MKDOCSTRINGS_AUTOREFS_PREFIX: _render_meta_content,
-    PYMD_ABBREVIATIONS_PREFIX: _render_pymd_abbr,
+    PYMD_ABBREVIATIONS_PREFIX: _render_inline_content,
 }
 
 

tests/render/fixtures/mkdocstrings_crossreference.md

@@ -0,0 +1,13 @@
+`mkdocstrings` cross-references
+.
+With a custom title:
+[`Object 1`][full.path.object1]
+
+With the identifier as title:
+[full.path.object2][]
+.
+<p>With a custom title:
+<a href="#full.path.object1"><code>Object 1</code></a></p>
+<p>With the identifier as title:
+<a href="#full.path.object2">full.path.object2</a></p>
+.

tests/render/test_render.py

@@ -8,6 +8,7 @@
     material_admon_plugin,
     material_content_tabs_plugin,
     mkdocstrings_autorefs_plugin,
+    mkdocstrings_crossreference_plugin,
     pymd_abbreviations_plugin,
 )
 
@@ -30,7 +31,10 @@ def with_plugin(filename, plugins):
         ),
         *with_plugin("mkdocstrings_autorefs.md", [mkdocstrings_autorefs_plugin]),
         *with_plugin("pymd_abbreviations.md", [pymd_abbreviations_plugin]),
-        # TODO: Test cross-reference!
+        *with_plugin(
+            "mkdocstrings_crossreference.md",
+            [mkdocstrings_crossreference_plugin],
+        ),
     ],
 )
 def test_render(line, title, text, expected, plugins):