mdformat-mkdocs 5.1.4__tar.gz → 5.2.0b0__tar.gz

{mdformat_mkdocs-5.1.4 → mdformat_mkdocs-5.2.0b0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdformat_mkdocs
-Version: 5.1.4
+Version: 5.2.0b0
 Summary: An mdformat plugin for mkdocs and Material for MkDocs
 Keywords: markdown,markdown-it,mdformat,mdformat_plugin_template
 Author: kyleking
@@ -62,6 +62,8 @@ Supports:
 - [MkDocs-Material Content Tabs\*](https://squidfunk.github.io/mkdocs-material/reference/content-tabs)
     - \*Note: the markup (HTML) rendered by this plugin is sufficient for formatting but not for viewing in a browser. Please open an issue if you have a need to generate valid HTML.
 - [MkDocs-Material Definition Lists](https://squidfunk.github.io/mkdocs-material/reference/lists/#using-definition-lists)
+- [mkdocstrings Injection Blocks](https://mkdocstrings.github.io/usage/)
+    - Preserves `:::` identifier blocks and their indented YAML options verbatim
 - [mkdocstrings Anchors (autorefs)](https://mkdocstrings.github.io/autorefs/#markdown-anchors)
 - [mkdocstrings Cross-References](https://mkdocstrings.github.io/usage/#cross-references)
 - [Python Markdown "Abbreviations"\*](https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-abbreviations)

{mdformat_mkdocs-5.1.4 → mdformat_mkdocs-5.2.0b0}/README.md

@@ -15,6 +15,8 @@ Supports:
 - [MkDocs-Material Content Tabs\*](https://squidfunk.github.io/mkdocs-material/reference/content-tabs)
     - \*Note: the markup (HTML) rendered by this plugin is sufficient for formatting but not for viewing in a browser. Please open an issue if you have a need to generate valid HTML.
 - [MkDocs-Material Definition Lists](https://squidfunk.github.io/mkdocs-material/reference/lists/#using-definition-lists)
+- [mkdocstrings Injection Blocks](https://mkdocstrings.github.io/usage/)
+    - Preserves `:::` identifier blocks and their indented YAML options verbatim
 - [mkdocstrings Anchors (autorefs)](https://mkdocstrings.github.io/autorefs/#markdown-anchors)
 - [mkdocstrings Cross-References](https://mkdocstrings.github.io/usage/#cross-references)
 - [Python Markdown "Abbreviations"\*](https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-abbreviations)

{mdformat_mkdocs-5.1.4 → mdformat_mkdocs-5.2.0b0}/mdformat_mkdocs/__init__.py

@@ -1,6 +1,7 @@
+# ruff: noqa: RUF067
 """An mdformat plugin for `mkdocs`."""
 
-__version__ = "5.1.4"
+__version__ = "5.2.0b0"
 
 __plugin_name__ = "mkdocs"
 

{mdformat_mkdocs-5.1.4 → mdformat_mkdocs-5.2.0b0}/mdformat_mkdocs/mdit_plugins/__init__.py

@@ -21,6 +21,10 @@ from ._mkdocstrings_crossreference import (
     MKDOCSTRINGS_CROSSREFERENCE_PREFIX,
     mkdocstrings_crossreference_plugin,
 )
+from ._mkdocstrings_injection import (
+    MKDOCSTRINGS_INJECTION_PREFIX,
+    mkdocstrings_injection_plugin,
+)
 from ._pymd_abbreviations import PYMD_ABBREVIATIONS_PREFIX, pymd_abbreviations_plugin
 from ._pymd_admon import pymd_admon_plugin
 from ._pymd_arithmatex import (
@@ -48,6 +52,7 @@ __all__ = (
     "MKDOCSTRINGS_AUTOREFS_PREFIX",
     "MKDOCSTRINGS_CROSSREFERENCE_PREFIX",
     "MKDOCSTRINGS_HEADING_AUTOREFS_PREFIX",
+    "MKDOCSTRINGS_INJECTION_PREFIX",
     "PYMD_ABBREVIATIONS_PREFIX",
     "PYMD_CAPTIONS_PREFIX",
     "PYMD_SNIPPET_PREFIX",
@@ -59,6 +64,7 @@ __all__ = (
     "material_deflist_plugin",
     "mkdocstrings_autorefs_plugin",
     "mkdocstrings_crossreference_plugin",
+    "mkdocstrings_injection_plugin",
     "pymd_abbreviations_plugin",
     "pymd_admon_plugin",
     "pymd_arithmatex_plugin",

mdformat_mkdocs-5.2.0b0/mdformat_mkdocs/mdit_plugins/_mkdocstrings_injection.py

@@ -0,0 +1,74 @@
+"""mkdocstrings injection blocks.
+
+Matches:
+
+```md
+::: package.module.Class
+    options:
+        heading_level: 2
+```
+
+Docs: https://mkdocstrings.github.io/usage/
+
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from mdit_py_plugins.utils import is_code_block
+
+if TYPE_CHECKING:
+    from markdown_it import MarkdownIt
+    from markdown_it.rules_block import StateBlock
+
+_INJECTION_PATTERN = re.compile(r"^:::\s+\S")
+MKDOCSTRINGS_INJECTION_PREFIX = "mkdocstrings_injection"
+
+
+def _get_line(state: StateBlock, line: int, base_indent: int) -> str:
+    return state.src[state.bMarks[line] + base_indent : state.eMarks[line]]
+
+
+def _mkdocstrings_injection(
+    state: StateBlock,
+    start_line: int,
+    end_line: int,
+    silent: bool,
+) -> bool:
+    if is_code_block(state, start_line):
+        return False
+
+    base_indent = state.blkIndent
+    header = _get_line(state, start_line, base_indent)
+    if not _INJECTION_PATTERN.match(header):
+        return False
+
+    if silent:
+        return True
+
+    lines = [header]
+    next_line = start_line + 1
+    while next_line < end_line:
+        if state.tShift[next_line] <= base_indent:
+            break
+        lines.append(_get_line(state, next_line, base_indent))
+        next_line += 1
+
+    token = state.push(MKDOCSTRINGS_INJECTION_PREFIX, "", 0)
+    token.content = "\n".join(lines)
+    token.block = True
+    token.map = [start_line, next_line]
+
+    state.line = next_line
+    return True
+
+
+def mkdocstrings_injection_plugin(md: MarkdownIt) -> None:
+    md.block.ruler.before(
+        "paragraph",
+        MKDOCSTRINGS_INJECTION_PREFIX,
+        _mkdocstrings_injection,
+        {"alt": ["paragraph"]},
+    )

{mdformat_mkdocs-5.1.4 → mdformat_mkdocs-5.2.0b0}/mdformat_mkdocs/mdit_plugins/_python_markdown_attr_list.py

@@ -40,13 +40,15 @@ def _python_markdown_attr_list(state: StateInline, silent: bool) -> bool:
 
     # Look backwards for unclosed '['
     search_start = max(0, state.pos - 100)  # Limit backwards search
-    text_before = state.src[search_start:state.pos]
+    text_before = state.src[search_start : state.pos]
     open_brackets = text_before.count("[") - text_before.count("]")
     if open_brackets > 0:
         # We might be inside a link, check if there's '](' after our match
         match_end_pos = state.pos + match.end()
         if match_end_pos < len(state.src):
-            lookahead = state.src[match_end_pos:min(match_end_pos + 100, len(state.src))]
+            lookahead = state.src[
+                match_end_pos : min(match_end_pos + 100, len(state.src))
+            ]
             if "](" in lookahead:
                 # Very likely inside link text, don't match
                 return False

{mdformat_mkdocs-5.1.4 → mdformat_mkdocs-5.2.0b0}/mdformat_mkdocs/plugin.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import re
 import textwrap
 from functools import partial
 from typing import TYPE_CHECKING
@@ -10,7 +11,7 @@ from mdformat.renderer import DEFAULT_RENDERERS, RenderContext, RenderTreeNode
 
 from ._helpers import ContextOptions, get_conf
 from ._normalize_list import normalize_list as unbounded_normalize_list
-from ._postprocess_inline import postprocess_list_wrap
+from ._postprocess_inline import postprocess_list_wrap as _postprocess_list_wrap
 from .mdit_plugins import (
     AMSMATH_BLOCK,
     DOLLARMATH_BLOCK,
@@ -19,6 +20,7 @@ from .mdit_plugins import (
     MKDOCSTRINGS_AUTOREFS_PREFIX,
     MKDOCSTRINGS_CROSSREFERENCE_PREFIX,
     MKDOCSTRINGS_HEADING_AUTOREFS_PREFIX,
+    MKDOCSTRINGS_INJECTION_PREFIX,
     PYMD_ABBREVIATIONS_PREFIX,
     PYMD_CAPTIONS_PREFIX,
     PYMD_SNIPPET_PREFIX,
@@ -30,6 +32,7 @@ from .mdit_plugins import (
     material_deflist_plugin,
     mkdocstrings_autorefs_plugin,
     mkdocstrings_crossreference_plugin,
+    mkdocstrings_injection_plugin,
     pymd_abbreviations_plugin,
     pymd_admon_plugin,
     pymd_arithmatex_plugin,
@@ -108,6 +111,7 @@ def update_mdit(mdit: MarkdownIt) -> None:
     mdit.use(material_content_tabs_plugin)
     mdit.use(material_deflist_plugin)
     mdit.use(mkdocstrings_autorefs_plugin)
+    mdit.use(mkdocstrings_injection_plugin)
     mdit.use(pymd_abbreviations_plugin)
     mdit.use(pymd_admon_plugin)
     mdit.use(pymd_snippet_plugin)
@@ -134,29 +138,42 @@ def _render_math_inline(node: RenderTreeNode, context: RenderContext) -> str:  #
     return f"${content}$"
 
 
+def _strip_blockquote_markers(content: str) -> str:
+    """Strip blockquote markers from math block content.
+
+    markdown-it includes "> " prefixes when block math appears inside blockquotes.
+    """
+    lines = content.split("\n")
+    return "\n".join(
+        line.removeprefix("> ") if line.startswith("> ") else line for line in lines
+    ).strip()
+
+
 def _render_math_block(node: RenderTreeNode, context: RenderContext) -> str:  # noqa: ARG001
     """Render block math with original delimiters."""
     markup = node.markup
-    content = node.content
+    cleaned_content = _strip_blockquote_markers(node.content)
+
     if markup == "$$":
-        return f"$$\n{content.strip()}\n$$"
+        return f"$$\n{cleaned_content}\n$$"
     if markup == "\\[":
-        return f"\\[\n{content.strip()}\n\\]"
+        return f"\\[\n{cleaned_content}\n\\]"
     # Fallback
-    return f"$$\n{content.strip()}\n$$"
+    return f"$$\n{cleaned_content}\n$$"
 
 
 def _render_math_block_eqno(node: RenderTreeNode, context: RenderContext) -> str:  # noqa: ARG001
     """Render block math with equation label."""
     markup = node.markup
-    content = node.content
-    label = node.info  # Label is stored in info field
+    label = node.info
+    cleaned_content = _strip_blockquote_markers(node.content)
+
     if markup == "$$":
-        return f"$$\n{content.strip()}\n$$ ({label})"
+        return f"$$\n{cleaned_content}\n$$ ({label})"
     if markup == "\\[":
-        return f"\\[\n{content.strip()}\n\\] ({label})"
+        return f"\\[\n{cleaned_content}\n\\] ({label})"
     # Fallback
-    return f"$$\n{content.strip()}\n$$ ({label})"
+    return f"$$\n{cleaned_content}\n$$ ({label})"
 
 
 def _render_amsmath(node: RenderTreeNode, context: RenderContext) -> str:  # noqa: ARG001
@@ -176,40 +193,53 @@ def _render_inline_content(node: RenderTreeNode, context: RenderContext) -> str:
     return inline.content
 
 
-def _render_code_inline(node: RenderTreeNode, context: RenderContext) -> str:
-    r"""Render inline code, cleaning up whitespace from newline normalization.
+_ESCAPED_LINK_SPACED_URL = re.compile(r"\\\[([^\]]*)\\\]\(([^)]*[ ][^)]*)\)")
+
+
+def _fix_links_with_spaced_urls(
+    text: str,
+    node: RenderTreeNode,  # noqa: ARG001
+    context: RenderContext,  # noqa: ARG001
+) -> str:
+    """Rewrite escaped links with space-containing URLs to angle-bracket syntax.
+
+    CommonMark requires link destinations with spaces to use angle brackets.
+    When markdown-it fails to parse [text](url with space) as a link, mdformat
+    escapes the brackets. Detects and repairs those cases.
+
+    Addresses: https://github.com/KyleKing/mdformat-mkdocs/issues/80
+
+    """
+    return _ESCAPED_LINK_SPACED_URL.sub(
+        lambda m: f"[{m.group(1)}](<{m.group(2)}>)",
+        text,
+    )
 
-    `markdown-it` normalizes newlines in inline code to spaces. This can result in
-    unintended trailing spaces from original newlines before closing backticks.
-    Per mdformat's own logic, trailing spaces are only intentional if there are
-    also leading spaces. So we strip trailing spaces when there's no leading space.
 
-    Example: `code\n` (newline) → `code ` (parsed) → `code` (rendered)
+def _render_text(node: RenderTreeNode, context: RenderContext) -> str:
+    r"""Re-escape dollar signs that mdformat core stripped.
 
-    This could break at any time, so this is a best effort to resolve issues like:
-    https://github.com/KyleKing/mdformat-mkdocs/issues/34#issuecomment-3589835341
+    mdformat removes "unnecessary" backslash escapes (\$ -> $), but with math enabled
+    those bare $ become math delimiters. Compares text content against the parent
+    inline token (which preserves backslashes) to detect and restore the escapes.
 
+    Related: https://github.com/KyleKing/mdformat-mkdocs/issues/77
     """
-    default_renderer = DEFAULT_RENDERERS.get("code_inline")
+    default_renderer = DEFAULT_RENDERERS.get("text")
     if default_renderer is None:
         return node.content
 
-    result = default_renderer(node, context)
+    text = default_renderer(node, context)
 
-    # Only process single-backtick code (not double-backtick code with embedded backticks)
-    if not (result.startswith("`") and result.endswith("`") and "``" not in result):
-        return result
-
-    content = result[1:-1]  # Strip opening and closing backticks
-    has_leading_space = content.startswith(" ")
-    has_trailing_space = content.endswith(" ")
+    if cli_is_no_mkdocs_math(context.options):
+        return text
 
-    # Strip trailing space only if there's no leading space and content is not all whitespace
-    # This preserves the mdformat rule: spaces are only intentional when both are present
-    if has_trailing_space and not has_leading_space and content.strip():
-        return f"`{content.rstrip(' ')}`"
+    if node.parent and node.parent.type == "inline":
+        parent_content = node.parent.content
+        if "$" in text and r"\$" in parent_content:
+            text = re.sub(r"(?<!\\)\$", r"\$", text)
 
-    return result
+    return text
 
 
 def _render_heading_autoref(node: RenderTreeNode, context: RenderContext) -> str:
@@ -307,12 +337,12 @@ RENDERERS: Mapping[str, Render] = {
     "admonition_title": render_admon_title,
     "admonition_mkdocs": add_extra_admon_newline,
     "admonition_mkdocs_title": render_admon_title,
-    "code_inline": _render_code_inline,
     "content_tab_mkdocs": add_extra_admon_newline,
     "content_tab_mkdocs_title": render_admon_title,
+    "dd": render_material_definition_body,
     "dl": render_material_definition_list,
     "dt": render_material_definition_term,
-    "dd": render_material_definition_body,
+    "text": _render_text,
     # Math support (from mdit-py-plugins)
     DOLLARMATH_INLINE: _render_math_inline,
     DOLLARMATH_BLOCK: _render_math_block,
@@ -323,6 +353,7 @@ RENDERERS: Mapping[str, Render] = {
     PYMD_CAPTIONS_PREFIX: render_pymd_caption,
     MKDOCSTRINGS_AUTOREFS_PREFIX: _render_meta_content,
     MKDOCSTRINGS_CROSSREFERENCE_PREFIX: _render_cross_reference,
+    MKDOCSTRINGS_INJECTION_PREFIX: _render_node_content,
     MKDOCSTRINGS_HEADING_AUTOREFS_PREFIX: _render_heading_autoref,
     PYMD_ABBREVIATIONS_PREFIX: _render_inline_content,
     PYMD_SNIPPET_PREFIX: _render_inline_content,
@@ -330,10 +361,24 @@ RENDERERS: Mapping[str, Render] = {
 }
 
 
-normalize_list = partial(
-    unbounded_normalize_list,  # type: ignore[has-type]
-    check_if_align_semantic_breaks_in_lists=cli_is_align_semantic_breaks_in_lists,
-)
+if TYPE_CHECKING:
+    normalize_list: Postprocess
+    postprocess_inline: Postprocess
+else:
+    normalize_list = partial(
+        unbounded_normalize_list,
+        check_if_align_semantic_breaks_in_lists=cli_is_align_semantic_breaks_in_lists,
+    )
+
+    def postprocess_inline(
+        text: str,
+        node: RenderTreeNode,
+        context: RenderContext,
+    ) -> str:
+        """Run all inline postprocessors in sequence."""
+        text = _postprocess_list_wrap(text, node, context)
+        return _fix_links_with_spaced_urls(text, node, context)
+
 
 # A mapping from `RenderTreeNode.type` to a `Postprocess` that does
 # postprocessing for the output of the `Render` function. Unlike
@@ -342,7 +387,7 @@ normalize_list = partial(
 # will run in series.
 POSTPROCESSORS: Mapping[str, Postprocess] = {
     "bullet_list": normalize_list,
-    "inline": postprocess_list_wrap,  # type: ignore[has-type]
+    "inline": postprocess_inline,
     "ordered_list": normalize_list,
     "paragraph": escape_deflist,
 }

{mdformat_mkdocs-5.1.4 → mdformat_mkdocs-5.2.0b0}/pyproject.toml

@@ -25,7 +25,7 @@ license-files = ["LICENSE"]
 name = "mdformat_mkdocs"
 readme = "README.md"
 requires-python = ">=3.10.0"
-version = "5.1.4"
+version = "5.2.0b0"
 
 [project.entry-points."mdformat.parser_extension"]
 mkdocs = "mdformat_mkdocs"
@@ -69,7 +69,7 @@ homepage = "https://github.com/kyleking/mdformat-mkdocs"
 
 [tool.commitizen]
 tag_format = "v${version}"
-version = "5.1.4"
+version = "5.2.0b0"
 version_files = ["mdformat_mkdocs/__init__.py", "pyproject.toml:^version"]
 
 [tool.mypy]