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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdformat_mkdocs
-Version: 5.1.4
+Version: 5.2.0
 Summary: An mdformat plugin for mkdocs and Material for MkDocs
 Keywords: markdown,markdown-it,mdformat,mdformat_plugin_template
 Author: kyleking
@@ -32,6 +32,7 @@ Requires-Dist: mdformat-hooks>=0.1.0 ; extra == 'recommended-mdsf'
 Requires-Dist: mdformat-simple-breaks>=0.0.1 ; extra == 'recommended-mdsf'
 Requires-Dist: mdformat-wikilink>=0.2.0 ; extra == 'recommended-mdsf'
 Requires-Dist: beartype>=0.21.0 ; extra == 'test'
+Requires-Dist: hypothesis>=6.100.0 ; extra == 'test'
 Requires-Dist: pytest>=9.0.1 ; extra == 'test'
 Requires-Dist: pytest-beartype>=0.2.0 ; extra == 'test'
 Requires-Dist: pytest-cov>=7.0.0 ; extra == 'test'
@@ -62,6 +63,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, including when nested inside lists with `--align-semantic-breaks-in-lists`
 - [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)
@@ -77,6 +80,23 @@ Supports:
 - [Python Markdown "Snippets"\*](https://facelessuser.github.io/pymdown-extensions/extensions/snippets)
     - \*Note: the markup (HTML) renders the plain text without implementing the snippet logic. I'm open to contributions if anyone needs full support for snippets
 
+### Features with Implicit Support
+
+The following MkDocs/Material/PyMdown syntax passes through mdformat-mkdocs unchanged — it is not modified or corrupted, but it is also not actively normalized:
+
+- [PyMdown Keys](https://facelessuser.github.io/pymdown-extensions/extensions/keys/) — `++ctrl+alt+del++` (not a markdown construct, preserved as-is)
+- [PyMdown Critic Markup](https://facelessuser.github.io/pymdown-extensions/extensions/critic/) — `{--deleted--}`, `{++added++}`, `{~~old~>new~~}`, `{==highlight==}`, `{>>comment<<}`
+- [PyMdown Highlight](https://facelessuser.github.io/pymdown-extensions/extensions/mark/) — `==marked text==`
+- [PyMdown Caret / Tilde](https://facelessuser.github.io/pymdown-extensions/extensions/caret/) — `H^2^O`, `CH~3~OH`
+- [PyMdown Emoji](https://facelessuser.github.io/pymdown-extensions/extensions/emoji/) — `:smile:`, `:material-icon:`
+- [PyMdown InlineHilite](https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/) — language hints inside backtick spans (`:::python code`) are never modified
+- [PyMdown SmartSymbols](https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/) — `(c)`, `(tm)`, `--`, `-->` are plain ASCII in source and not touched
+- [PyMdown MagicLink](https://facelessuser.github.io/pymdown-extensions/extensions/magiclink/) — `@username`, `#123` are plain text and pass through
+- [Material Grids](https://squidfunk.github.io/mkdocs-material/reference/grids/) — `<div class="grid cards" markdown>` is an HTML block; content is preserved but markdown inside is not reformatted
+- [Mermaid / Superfences](https://squidfunk.github.io/mkdocs-material/reference/diagrams/) — diagram code inside fenced blocks is never modified
+
+**Note on [PyMdown ProgressBar](https://facelessuser.github.io/pymdown-extensions/extensions/progressbar/)**: The syntax `[=50% "50%"]` resembles an undefined link reference and will be escaped to `\[=50% "50%"\]` by default. Use `--ignore-missing-references` to preserve it, or avoid this extension if you use mdformat without that flag.
+
 See the example test files, [./tests/pre-commit-test.md](https://raw.githubusercontent.com/KyleKing/mdformat-mkdocs/main/tests/pre-commit-test.md) and [./tests/format/fixtures.md](https://raw.githubusercontent.com/KyleKing/mdformat-mkdocs/main/tests/format/fixtures.md)
 
 ## `mdformat` Usage

{mdformat_mkdocs-5.1.4 → mdformat_mkdocs-5.2.0}/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, including when nested inside lists with `--align-semantic-breaks-in-lists`
 - [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)
@@ -30,6 +32,23 @@ Supports:
 - [Python Markdown "Snippets"\*](https://facelessuser.github.io/pymdown-extensions/extensions/snippets)
     - \*Note: the markup (HTML) renders the plain text without implementing the snippet logic. I'm open to contributions if anyone needs full support for snippets
 
+### Features with Implicit Support
+
+The following MkDocs/Material/PyMdown syntax passes through mdformat-mkdocs unchanged — it is not modified or corrupted, but it is also not actively normalized:
+
+- [PyMdown Keys](https://facelessuser.github.io/pymdown-extensions/extensions/keys/) — `++ctrl+alt+del++` (not a markdown construct, preserved as-is)
+- [PyMdown Critic Markup](https://facelessuser.github.io/pymdown-extensions/extensions/critic/) — `{--deleted--}`, `{++added++}`, `{~~old~>new~~}`, `{==highlight==}`, `{>>comment<<}`
+- [PyMdown Highlight](https://facelessuser.github.io/pymdown-extensions/extensions/mark/) — `==marked text==`
+- [PyMdown Caret / Tilde](https://facelessuser.github.io/pymdown-extensions/extensions/caret/) — `H^2^O`, `CH~3~OH`
+- [PyMdown Emoji](https://facelessuser.github.io/pymdown-extensions/extensions/emoji/) — `:smile:`, `:material-icon:`
+- [PyMdown InlineHilite](https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/) — language hints inside backtick spans (`:::python code`) are never modified
+- [PyMdown SmartSymbols](https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/) — `(c)`, `(tm)`, `--`, `-->` are plain ASCII in source and not touched
+- [PyMdown MagicLink](https://facelessuser.github.io/pymdown-extensions/extensions/magiclink/) — `@username`, `#123` are plain text and pass through
+- [Material Grids](https://squidfunk.github.io/mkdocs-material/reference/grids/) — `<div class="grid cards" markdown>` is an HTML block; content is preserved but markdown inside is not reformatted
+- [Mermaid / Superfences](https://squidfunk.github.io/mkdocs-material/reference/diagrams/) — diagram code inside fenced blocks is never modified
+
+**Note on [PyMdown ProgressBar](https://facelessuser.github.io/pymdown-extensions/extensions/progressbar/)**: The syntax `[=50% "50%"]` resembles an undefined link reference and will be escaped to `\[=50% "50%"\]` by default. Use `--ignore-missing-references` to preserve it, or avoid this extension if you use mdformat without that flag.
+
 See the example test files, [./tests/pre-commit-test.md](https://raw.githubusercontent.com/KyleKing/mdformat-mkdocs/main/tests/pre-commit-test.md) and [./tests/format/fixtures.md](https://raw.githubusercontent.com/KyleKing/mdformat-mkdocs/main/tests/format/fixtures.md)
 
 ## `mdformat` Usage

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

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

{mdformat_mkdocs-5.1.4 → mdformat_mkdocs-5.2.0}/mdformat_mkdocs/_helpers.py

@@ -15,7 +15,7 @@ EOL = "\n"
 MKDOCS_INDENT_COUNT = 4
 """Use 4-spaces for mkdocs."""
 
-FILLER_CHAR = "𝕏"  # noqa: RUF001
+FILLER_CHAR = ""
 """A spacer that is inserted and then removed to ensure proper word wrap."""
 
 

{mdformat_mkdocs-5.1.4 → mdformat_mkdocs-5.2.0}/mdformat_mkdocs/_normalize_list.py

@@ -19,7 +19,11 @@ from ._helpers import (
     rstrip_result,
     separate_indent,
 )
-from .mdit_plugins import MATERIAL_ADMON_MARKERS, MATERIAL_CONTENT_TAB_MARKERS
+from .mdit_plugins import (
+    INJECTION_PATTERN,
+    MATERIAL_ADMON_MARKERS,
+    MATERIAL_CONTENT_TAB_MARKERS,
+)
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
@@ -71,6 +75,7 @@ class Syntax(Enum):
     START_MARKED = "START_MARKED"
     EDGE_CODE = "EDGE_CODE"
     HTML = "HTML"
+    INJECTION = "INJECTION"
 
     @classmethod
     def from_content(cls, content: str) -> Syntax | None:
@@ -85,18 +90,25 @@ class Syntax(Enum):
             if match["item"].startswith("```"):
                 return cls.CODE_NUMBERED if is_numbered else cls.CODE_BULLETED
             return cls.LIST_NUMBERED if is_numbered else cls.LIST_BULLETED
+
+        result = None
         if any(content.startswith(f"{marker} ") for marker in MARKERS):
-            return cls.START_MARKED
-        if content.startswith("```"):
-            return cls.EDGE_CODE
-        if content.startswith("<"):
-            return cls.HTML
-        return None
+            result = cls.START_MARKED
+        elif content.startswith("```"):
+            result = cls.EDGE_CODE
+        elif content.startswith("<"):
+            result = cls.HTML
+        elif INJECTION_PATTERN.match(content):
+            result = cls.INJECTION
+        return result
 
 
 SYNTAX_CODE_LIST = {Syntax.CODE_BULLETED, Syntax.CODE_NUMBERED}
 """The start of a code block, which is also the start of a list."""
 
+SYNTAX_LIST = {Syntax.LIST_BULLETED, Syntax.LIST_NUMBERED, *SYNTAX_CODE_LIST}
+"""Any line that begins a list item."""
+
 
 class ParsedLine(NamedTuple):
     """Parsed Line of text."""
@@ -212,7 +224,7 @@ class BlockIndent(NamedTuple):
     start_line: int
     raw_indent: str
     indent_depth: int
-    kind: Literal["code", "HTML"]
+    kind: Literal["code", "HTML", "injection"]
 
 
 def _parse_code_block(last: BlockIndent | None, line: LineResult) -> BlockIndent | None:
@@ -251,9 +263,44 @@ def _parse_html_line(last: BlockIndent | None, line: LineResult) -> BlockIndent
     elif last and not line.parsed.content:
         # Stop tracking an HTML block on a line break
         result = None
+    elif (
+        last
+        and line.parsed.syntax in SYNTAX_LIST
+        and len(line.parsed.indent) < len(last.raw_indent)
+    ):
+        # A list item that dedents below the block is a sibling, not HTML
+        #   content. This guards against an inline autolink (or comment) on a
+        #   continuation line being mistaken for a block that swallows siblings.
+        result = None
     return result
 
 
+def _parse_injection_block(
+    last: BlockIndent | None,
+    line: LineResult,
+) -> BlockIndent | None:
+    """Identify mkdocstrings injection sections."""
+    if last is not None:
+        if line.parsed.content and len(line.parsed.indent) <= len(last.raw_indent):
+            if line.parsed.syntax == Syntax.INJECTION:
+                return BlockIndent(
+                    start_line=line.parsed.line_num,
+                    raw_indent=line.parsed.indent,
+                    indent_depth=len(line.parents),
+                    kind="injection",
+                )
+            return None
+        return last
+    if line.parsed.syntax == Syntax.INJECTION:
+        return BlockIndent(
+            start_line=line.parsed.line_num,
+            raw_indent=line.parsed.indent,
+            indent_depth=len(line.parents),
+            kind="injection",
+        )
+    return None
+
+
 # ======================================================================================
 # Semantic Indent Handling
 
@@ -274,12 +321,11 @@ def _parse_semantic_indent(
     tin: tuple[LineResult, BlockIndent | None],
 ) -> SemanticIndent:
     """Conditionally evaluate when semantic indents are necessary."""
-    # PLANNED: This works, but is very confusing
-    line, code_indent = tin
+    line, block_indent = tin
 
     if (
         not line.parsed.content
-        or code_indent is not None
+        or block_indent is not None
         or line.parsed.syntax in SYNTAX_CODE_LIST
     ):
         result = SemanticIndent.EMPTY
@@ -420,22 +466,36 @@ def parse_text(
         indent if (indent and code_indents[indent.start_line] is None) else None
         for indent in map_lookback(_parse_html_line, lines, None)
     ]
-    # When both, code_indents take precedence
+    injection_indents = [
+        # Any indents initiated from within a `code_block_indents` should be ignored
+        indent if (indent and code_indents[indent.start_line] is None) else None
+        for indent in map_lookback(_parse_injection_block, lines, None)
+    ]
+    # When multiple match, code_indents take precedence, then html_indents
     block_indents = [
-        c_ or h_ for c_, h_ in zip(code_indents, html_indents, strict=True)
+        c_ or h_ or i_
+        for c_, h_, i_ in zip(
+            code_indents, html_indents, injection_indents, strict=True
+        )
     ]
     new_indents = [*starmap(_format_new_indent, zip(lines, block_indents, strict=True))]
 
     new_contents = [
-        _format_new_content(line, inc_numbers, ci is not None)
-        for line, ci in zip(lines, code_indents, strict=True)
+        _format_new_content(
+            line,
+            inc_numbers,
+            block_indent is not None and block_indent.kind in {"code", "injection"},
+        )
+        for line, block_indent in zip(lines, block_indents, strict=True)
     ]
 
     if use_sem_break:
         semantic_indents = map_lookback(
             _parse_semantic_indent,
-            [*zip(lines, code_indents, strict=True)],
-            _parse_semantic_indent(SemanticIndent.INITIAL, (lines[0], code_indents[0])),
+            [*zip(lines, block_indents, strict=True)],
+            _parse_semantic_indent(
+                SemanticIndent.INITIAL, (lines[0], block_indents[0])
+            ),
         )
         new_indents = [
             _trim_semantic_indent(indent, s_i, in_defbody)

{mdformat_mkdocs-5.1.4 → mdformat_mkdocs-5.2.0}/mdformat_mkdocs/_synced/admon_factories/_whitespace_admon_factories.py

@@ -189,8 +189,10 @@ def new_token(
     kind: str,
 ) -> Generator[Token, None, None]:
     """Create scoped token."""
-    yield state.push(f"{name}_open", kind, 1)
-    state.push(f"{name}_close", kind, -1)
+    try:
+        yield state.push(f"{name}_open", kind, 1)
+    finally:
+        state.push(f"{name}_close", kind, -1)
 
 
 def default_render(

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

@@ -21,6 +21,11 @@ from ._mkdocstrings_crossreference import (
     MKDOCSTRINGS_CROSSREFERENCE_PREFIX,
     mkdocstrings_crossreference_plugin,
 )
+from ._mkdocstrings_injection import (
+    INJECTION_PATTERN,
+    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 (
@@ -37,21 +42,25 @@ from ._python_markdown_attr_list import (
     PYTHON_MARKDOWN_ATTR_LIST_PREFIX,
     python_markdown_attr_list_plugin,
 )
+from ._spaced_url_link import SPACED_URL_LINK_PREFIX, spaced_url_link_plugin
 
 __all__ = (
     "AMSMATH_BLOCK",
     "DOLLARMATH_BLOCK",
     "DOLLARMATH_BLOCK_LABEL",
     "DOLLARMATH_INLINE",
+    "INJECTION_PATTERN",
     "MATERIAL_ADMON_MARKERS",
     "MATERIAL_CONTENT_TAB_MARKERS",
     "MKDOCSTRINGS_AUTOREFS_PREFIX",
     "MKDOCSTRINGS_CROSSREFERENCE_PREFIX",
     "MKDOCSTRINGS_HEADING_AUTOREFS_PREFIX",
+    "MKDOCSTRINGS_INJECTION_PREFIX",
     "PYMD_ABBREVIATIONS_PREFIX",
     "PYMD_CAPTIONS_PREFIX",
     "PYMD_SNIPPET_PREFIX",
     "PYTHON_MARKDOWN_ATTR_LIST_PREFIX",
+    "SPACED_URL_LINK_PREFIX",
     "TEXMATH_BLOCK_EQNO",
     "escape_deflist",
     "material_admon_plugin",
@@ -59,6 +68,7 @@ __all__ = (
     "material_deflist_plugin",
     "mkdocstrings_autorefs_plugin",
     "mkdocstrings_crossreference_plugin",
+    "mkdocstrings_injection_plugin",
     "pymd_abbreviations_plugin",
     "pymd_admon_plugin",
     "pymd_arithmatex_plugin",
@@ -68,4 +78,5 @@ __all__ = (
     "render_material_definition_body",
     "render_material_definition_list",
     "render_material_definition_term",
+    "spaced_url_link_plugin",
 )

{mdformat_mkdocs-5.1.4 → mdformat_mkdocs-5.2.0}/mdformat_mkdocs/mdit_plugins/_material_deflist.py

@@ -35,7 +35,6 @@ from markdown_it import MarkdownIt
 from mdit_py_plugins.deflist import deflist_plugin
 
 if TYPE_CHECKING:
-    from markdown_it import MarkdownIt
     from mdformat.renderer import RenderContext, RenderTreeNode
     from mdformat.renderer.typing import Render
 

{mdformat_mkdocs-5.1.4 → mdformat_mkdocs-5.2.0}/mdformat_mkdocs/mdit_plugins/_mkdocstrings_autorefs.py

@@ -35,6 +35,7 @@ def _mkdocstrings_autorefs_plugin(state: StateInline, silent: bool) -> bool:
         return False
 
     if silent:
+        state.pos += match.end()  # skipToken only auto-advances when ok=False
         return True
 
     anchor = match["anchor"]

{mdformat_mkdocs-5.1.4 → mdformat_mkdocs-5.2.0}/mdformat_mkdocs/mdit_plugins/_mkdocstrings_crossreference.py

@@ -28,6 +28,7 @@ def _mkdocstrings_crossreference(state: StateInline, silent: bool) -> bool:
         return False
 
     if silent:
+        state.pos += match.end()  # skipToken only auto-advances when ok=False
         return True
 
     original_pos = state.pos

mdformat_mkdocs-5.2.0/mdformat_mkdocs/mdit_plugins/_mkdocstrings_injection.py

@@ -0,0 +1,78 @@
+"""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.tShift[start_line]
+    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 not state.isEmpty(next_line) and state.tShift[next_line] <= base_indent:
+            break
+        lines.append(_get_line(state, next_line, base_indent))
+        next_line += 1
+
+    while len(lines) > 1 and not lines[-1].strip():
+        lines.pop()
+        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.0}/mdformat_mkdocs/mdit_plugins/_python_markdown_attr_list.py

@@ -17,7 +17,6 @@ from markdown_it import MarkdownIt
 from mdformat_mkdocs._synced.admon_factories import new_token
 
 if TYPE_CHECKING:
-    from markdown_it import MarkdownIt
     from markdown_it.rules_inline import StateInline
 
 _ATTR_LIST_PATTERN = re.compile(r"{:? (?P<attrs>[^}]+) }")
@@ -38,20 +37,22 @@ def _python_markdown_attr_list(state: StateInline, silent: bool) -> bool:
     if state.linkLevel > 0:
         return False
 
-    # Look backwards for unclosed '['
-    search_start = max(0, state.pos - 100)  # Limit backwards search
-    text_before = state.src[search_start:state.pos]
+    # Look backwards for unclosed '[' — no length cap; any fixed cap fails for long URLs.
+    text_before = state.src[: 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
 
     if silent:
+        state.pos += match.end()  # skipToken only auto-advances when ok=False
         return True
 
     original_pos = state.pos

mdformat_mkdocs-5.2.0/mdformat_mkdocs/mdit_plugins/_spaced_url_link.py

@@ -0,0 +1,78 @@
+"""Inline rule: parse ``[text](url with spaces)`` as a link.
+
+CommonMark requires angle brackets for link destinations containing spaces.
+Python-Markdown/MkDocs users write these without angle brackets. Without
+this rule, markdown-it treats the whole construct as plain text, and
+mdformat's HTML stability check fires.
+
+This rule fires BEFORE markdown-it's built-in link rule. When it detects a
+URL with at least one literal space (and no angle brackets), it emits proper
+link tokens with the space percent-encoded in the href, matching the HTML
+that mdformat outputs for the corrected form ``[text](<url with spaces>)``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from markdown_it import MarkdownIt
+
+if TYPE_CHECKING:
+    from markdown_it.rules_inline import StateInline
+
+SPACED_URL_LINK_PREFIX = "spaced_url_link"
+
+
+def _spaced_url_link(state: StateInline, silent: bool) -> bool:
+    src = state.src
+    pos = state.pos
+
+    if src[pos] != "[":
+        return False
+
+    bracket_end = src.find("]", pos + 1)
+    if bracket_end == -1 or bracket_end + 1 >= len(src) or src[bracket_end + 1] != "(":
+        return False
+
+    paren_start = bracket_end + 2
+    paren_end = src.find(")", paren_start)
+    if paren_end == -1:
+        return False
+
+    url = src[paren_start:paren_end]
+    if " " not in url or url.startswith("<"):
+        return False
+
+    first_space = url.index(" ")
+    char_after_space = url[first_space + 1] if first_space + 1 < len(url) else ""
+    if char_after_space in {'"', "'", "("}:
+        return False
+
+    if not silent:
+        old_pos_max = state.posMax
+
+        token = state.push("link_open", "a", 1)
+        token.attrs = {"href": url.replace(" ", "%20")}
+        token.markup = ""
+        token.info = ""
+
+        state.pos = pos + 1
+        state.posMax = bracket_end
+        state.linkLevel += 1
+        state.md.inline.tokenize(state)
+        state.linkLevel -= 1
+        state.posMax = old_pos_max
+
+        state.push("link_close", "a", -1)
+
+    state.pos = paren_end + 1
+    return True
+
+
+def spaced_url_link_plugin(md: MarkdownIt) -> None:
+    """Register the spaced-URL inline rule before the built-in link rule."""
+    md.inline.ruler.before(
+        "link",
+        SPACED_URL_LINK_PREFIX,
+        _spaced_url_link,
+    )

{mdformat_mkdocs-5.1.4 → mdformat_mkdocs-5.2.0}/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,
@@ -39,6 +42,7 @@ from .mdit_plugins import (
     render_material_definition_body,
     render_material_definition_list,
     render_material_definition_term,
+    spaced_url_link_plugin,
 )
 
 if TYPE_CHECKING:
@@ -108,10 +112,12 @@ 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)
     mdit.use(python_markdown_attr_list_plugin)
+    mdit.use(spaced_url_link_plugin)
 
     if cli_is_ignore_missing_references(mdit.options):
         mdit.use(mkdocstrings_crossreference_plugin)
@@ -134,29 +140,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 +195,82 @@ 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"\\\[([^\]]*)\\\]\(([^)]*[ ][^)]*)\)")
+_PERCENT_ENCODED_URL_LINK = re.compile(r"\[([^\]]*)\]\(([^)]*%20[^)]*)\)")
+_ANGLE_BRACKET_SPACED_URL_SOURCE = re.compile(r"\]\(<([^>]* [^>]*)>\)")
+_UNBRACKETED_SPACED_URL_SOURCE = re.compile(r"\]\(([^<>()]*\s[^<>()]*)\)")
+
+
+def _fix_links_with_spaced_urls(
+    text: str,
+    node: RenderTreeNode,
+    context: RenderContext,  # noqa: ARG001
+) -> str:
+    r"""Rewrite links with space-containing URLs to angle-bracket syntax.
+
+    CommonMark requires link destinations with spaces to use angle brackets.
+    Handles three cases:
+
+    1. markdown-it fails to parse [text](url space) as a link and mdformat
+       escapes the brackets — detects ``\\[text\\](url space)`` and rewrites to
+       ``[text](<url space>)``. (Fallback for edge cases not caught by the
+       spaced_url_link mdit rule.)
+    2. markdown-it parses [text](<url space>) correctly but percent-encodes
+       the space in the href — detects [text](url%20space) and restores to
+       [text](<url space>) using the original source in node.content.
+    3. The spaced_url_link mdit rule parses [text](url space) as a link with
+       percent-encoded href — same rewrite as case 2, but source has no
+       angle brackets so a separate pattern extracts the original URL.
+
+    Addresses: https://github.com/KyleKing/mdformat-mkdocs/issues/80
+
+    """
+    text = _ESCAPED_LINK_SPACED_URL.sub(
+        lambda m: f"[{m.group(1)}](<{m.group(2)}>)",
+        text,
+    )
+
+    spaced_urls_from_source = {
+        m.group(1) for m in _ANGLE_BRACKET_SPACED_URL_SOURCE.finditer(node.content)
+    } | {m.group(1) for m in _UNBRACKETED_SPACED_URL_SOURCE.finditer(node.content)}
+    if spaced_urls_from_source:
 
-    `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.
+        def _restore_spaced_url(m: re.Match[str]) -> str:
+            link_text, encoded_url = m.group(1), m.group(2)
+            decoded_url = encoded_url.replace("%20", " ")
+            if decoded_url in spaced_urls_from_source:
+                return f"[{link_text}](<{decoded_url}>)"
+            return m.group(0)
 
-    Example: `code\n` (newline) → `code ` (parsed) → `code` (rendered)
+        text = _PERCENT_ENCODED_URL_LINK.sub(_restore_spaced_url, text)
+
+    return text
 
-    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
 
+def _render_text(node: RenderTreeNode, context: RenderContext) -> str:
+    r"""Re-escape dollar signs that mdformat core stripped.
+
+    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)
-
-    # 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
+    text = default_renderer(node, context)
 
-    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 +368,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 +384,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 +392,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 +418,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.0}/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.0"
 
 [project.entry-points."mdformat.parser_extension"]
 mkdocs = "mdformat_mkdocs"
@@ -56,6 +56,7 @@ recommended-mdsf = [
 ]
 test = [
   "beartype >= 0.21.0",
+  "hypothesis >= 6.100.0",
   "pytest >= 9.0.1",
   "pytest-beartype >= 0.2.0",
   "pytest-cov >= 7.0.0",
@@ -69,7 +70,7 @@ homepage = "https://github.com/kyleking/mdformat-mkdocs"
 
 [tool.commitizen]
 tag_format = "v${version}"
-version = "5.1.4"
+version = "5.2.0"
 version_files = ["mdformat_mkdocs/__init__.py", "pyproject.toml:^version"]
 
 [tool.mypy]
@@ -183,6 +184,13 @@ isolated_build = true
 requires = ["tox>=4.32.0"]
 skip_missing_interpreters = false
 
+[tool.tox.env.canary]
+basepython = ["py314"]
+changedir = "{tox_root}"
+commands = [["python", "scripts/canary.py", {default = [], extend = true, replace = "posargs"}]]
+description = "Run mdformat --check against real downstream repos. Optionally specify: '-- ruff uv' to test a subset."
+skip_install = false
+
 [tool.tox.env.cz]
 basepython = ["py314"]
 commands = [["cz", "bump", {default = [], extend = true, replace = "posargs"}]]