mdformat-mkdocs 5.1.5b0__tar.gz → 5.2.0b0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdformat_mkdocs
-Version: 5.1.5b0
+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.5b0 → 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.5b0 → mdformat_mkdocs-5.2.0b0}/mdformat_mkdocs/__init__.py

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

{mdformat_mkdocs-5.1.5b0 → 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.5b0 → mdformat_mkdocs-5.2.0b0}/mdformat_mkdocs/plugin.py

@@ -20,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,
@@ -31,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,
@@ -109,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)
@@ -190,6 +193,29 @@ def _render_inline_content(node: RenderTreeNode, context: RenderContext) -> str:
     return inline.content
 
 
+_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,
+    )
+
+
 def _render_text(node: RenderTreeNode, context: RenderContext) -> str:
     r"""Re-escape dollar signs that mdformat core stripped.
 
@@ -327,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,
@@ -336,13 +363,22 @@ RENDERERS: Mapping[str, Render] = {
 
 if TYPE_CHECKING:
     normalize_list: Postprocess
-    postprocess_list_wrap: 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,
     )
-    postprocess_list_wrap = _postprocess_list_wrap
+
+    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
@@ -351,7 +387,7 @@ else:
 # will run in series.
 POSTPROCESSORS: Mapping[str, Postprocess] = {
     "bullet_list": normalize_list,
-    "inline": postprocess_list_wrap,
+    "inline": postprocess_inline,
     "ordered_list": normalize_list,
     "paragraph": escape_deflist,
 }

{mdformat_mkdocs-5.1.5b0 → 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.5b0"
+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.5b0"
+version = "5.2.0b0"
 version_files = ["mdformat_mkdocs/__init__.py", "pyproject.toml:^version"]
 
 [tool.mypy]