From 63280b63a8ed4496619eea3a9a1c80f54458709e Mon Sep 17 00:00:00 2001
From: Kyle King <KyleKing@users.noreply.github.com>
Date: Wed, 30 Oct 2024 06:00:02 -0400
Subject: [PATCH 1/6] test: add red test

---
 tests/format/fixtures/text.md | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/tests/format/fixtures/text.md b/tests/format/fixtures/text.md
index 141e93b..750ecde 100644
--- a/tests/format/fixtures/text.md
+++ b/tests/format/fixtures/text.md
@@ -1650,3 +1650,38 @@ Support inline bulleted code (https://github.com/KyleKing/mdformat-mkdocs/issues
           iex (new-object net.webclient).DownloadString('https://get.scoop.sh')
           ```
 .
+
+pymdown snippets (https://github.com/KyleKing/mdformat-mkdocs/issues/34)
+.
+# Snippets
+
+--8<-- "filename.ext"
+
+--8<-- "; skip.md"
+
+
+--8<--
+filename.md
+filename.log
+--8<--
+
+Content of file A.
+
+Content of file B.
+.
+# Snippets
+
+--8<-- "filename.ext"
+
+--8<-- "; skip.md"
+
+
+--8<--
+filename.md
+filename.log
+--8<--
+
+Content of file A.
+
+Content of file B.
+.

From 4e09a7fce15c6b7fc8b3210dd9b80c17dca11281 Mon Sep 17 00:00:00 2001
From: Kyle King <KyleKing@users.noreply.github.com>
Date: Mon, 16 Dec 2024 06:17:13 -0500
Subject: [PATCH 2/6] fix(#34): do not break pymd snippets

---
 mdformat_mkdocs/mdit_plugins/__init__.py      |  3 +
 mdformat_mkdocs/mdit_plugins/_pymd_snippet.py | 72 +++++++++++++++++++
 mdformat_mkdocs/plugin.py                     |  6 +-
 3 files changed, 80 insertions(+), 1 deletion(-)
 create mode 100644 mdformat_mkdocs/mdit_plugins/_pymd_snippet.py

diff --git a/mdformat_mkdocs/mdit_plugins/__init__.py b/mdformat_mkdocs/mdit_plugins/__init__.py
index 565d1d9..2fec958 100644
--- a/mdformat_mkdocs/mdit_plugins/__init__.py
+++ b/mdformat_mkdocs/mdit_plugins/__init__.py
@@ -15,6 +15,7 @@
     mkdocstrings_crossreference_plugin,
 )
 from ._pymd_abbreviations import PYMD_ABBREVIATIONS_PREFIX, pymd_abbreviations_plugin
+from ._pymd_snippet import PYMD_SNIPPET_PREFIX, pymd_snippet_plugin
 from ._python_markdown_admon import python_markdown_admon_plugin
 
 __all__ = (
@@ -24,10 +25,12 @@
     "MKDOCSTRINGS_CROSSREFERENCE_PREFIX",
     "MKDOCSTRINGS_HEADING_AUTOREFS_PREFIX",
     "PYMD_ABBREVIATIONS_PREFIX",
+    "PYMD_SNIPPET_PREFIX",
     "material_admon_plugin",
     "material_content_tabs_plugin",
     "mkdocstrings_autorefs_plugin",
     "mkdocstrings_crossreference_plugin",
     "pymd_abbreviations_plugin",
+    "pymd_snippet_plugin",
     "python_markdown_admon_plugin",
 )
diff --git a/mdformat_mkdocs/mdit_plugins/_pymd_snippet.py b/mdformat_mkdocs/mdit_plugins/_pymd_snippet.py
new file mode 100644
index 0000000..559ad6e
--- /dev/null
+++ b/mdformat_mkdocs/mdit_plugins/_pymd_snippet.py
@@ -0,0 +1,72 @@
+"""Python-Markdown Snippets.
+
+WARNING: matches only the "scissors" portion, leaving the rest unparsed
+
+```md
+--8<-- ...
+```
+
+Docs: <https://facelessuser.github.io/pymd-extensions/extensions/snippets>
+
+"""
+
+from __future__ import annotations
+
+import re
+
+from markdown_it import MarkdownIt
+from markdown_it.rules_block import StateBlock
+from mdit_py_plugins.utils import is_code_block
+
+from mdformat_mkdocs._synced.admon_factories import new_token
+
+# _SNIPPET_MARKER = "--8<--"
+_ABBREVIATION_PATTERN = re.compile(
+    r"--8<-- (?P<label>.+)",
+)
+PYMD_SNIPPET_PREFIX = "pymd_snippet"
+
+
+def _new_match(state: StateBlock, start_line: int) -> re.Match[str] | None:
+    """Determine match between start and end lines."""
+    start = state.bMarks[start_line] + state.tShift[start_line]
+    maximum = state.eMarks[start_line]
+    return _ABBREVIATION_PATTERN.match(state.src[start:maximum])
+
+
+def _pymd_snippet(
+    state: StateBlock,
+    start_line: int,
+    end_line: int,
+    silent: bool,
+) -> bool:
+    if is_code_block(state, start_line):
+        return False
+
+    match = _new_match(state, start_line)
+    if match is None:
+        return False
+
+    if silent:
+        return True
+
+    max_line = start_line
+
+    with new_token(state, PYMD_SNIPPET_PREFIX, "p"):
+        tkn_inline = state.push("inline", "", 0)
+        tkn_inline.content = match["label"]
+        tkn_inline.map = [start_line, max_line]
+        tkn_inline.children = []
+
+    state.line = max_line
+
+    return True
+
+
+def pymd_snippet_plugin(md: MarkdownIt) -> None:
+    md.block.ruler.before(
+        "reference",
+        PYMD_SNIPPET_PREFIX,
+        _pymd_snippet,
+        {"alt": ["paragraph"]},
+    )
diff --git a/mdformat_mkdocs/plugin.py b/mdformat_mkdocs/plugin.py
index c3d5db6..5b2d6ac 100644
--- a/mdformat_mkdocs/plugin.py
+++ b/mdformat_mkdocs/plugin.py
@@ -19,11 +19,13 @@
     MKDOCSTRINGS_CROSSREFERENCE_PREFIX,
     MKDOCSTRINGS_HEADING_AUTOREFS_PREFIX,
     PYMD_ABBREVIATIONS_PREFIX,
+    PYMD_SNIPPET_PREFIX,
     material_admon_plugin,
     material_content_tabs_plugin,
     mkdocstrings_autorefs_plugin,
     mkdocstrings_crossreference_plugin,
     pymd_abbreviations_plugin,
+    pymd_snippet_plugin,
     python_markdown_admon_plugin,
 )
 
@@ -69,7 +71,8 @@ def update_mdit(mdit: MarkdownIt) -> None:
     mdit.use(material_content_tabs_plugin)
     mdit.use(mkdocstrings_autorefs_plugin)
     mdit.use(pymd_abbreviations_plugin)
-    mdit.use(python_markdown_admon_plugin)
+    mdit.use(pymd_snippet_plugin)
+    mdit.use(python_markdown_admon_plugin)  # FIXME: standardize pymd name
 
     if cli_is_ignore_missing_references(mdit.options):
         mdit.use(mkdocstrings_crossreference_plugin)
@@ -179,6 +182,7 @@ def add_extra_admon_newline(node: RenderTreeNode, context: RenderContext) -> str
     MKDOCSTRINGS_HEADING_AUTOREFS_PREFIX: _render_heading_autoref,
     MKDOCSTRINGS_CROSSREFERENCE_PREFIX: _render_cross_reference,
     PYMD_ABBREVIATIONS_PREFIX: _render_inline_content,
+    PYMD_SNIPPET_PREFIX: _render_inline_content,
 }
 
 

From d9fee22a298a111be610e3ee2d28ca16aae6f9ba Mon Sep 17 00:00:00 2001
From: Kyle King <KyleKing@users.noreply.github.com>
Date: Mon, 16 Dec 2024 20:19:45 -0500
Subject: [PATCH 3/6] test: refactor pymd_snippets tests

---
 tests/format/fixtures/pymd_snippet.md         | 33 +++++++++++++++++
 tests/format/fixtures/text.md                 | 35 -------------------
 tests/format/test_format.py                   |  1 +
 ...admonitions.md => material_admonitions.md} |  0
 tests/render/fixtures/pymd_snippet.md         | 19 ++++++++++
 tests/render/test_render.py                   |  2 +-
 6 files changed, 54 insertions(+), 36 deletions(-)
 create mode 100644 tests/format/fixtures/pymd_snippet.md
 rename tests/render/fixtures/{matieral_admonitions.md => material_admonitions.md} (100%)
 create mode 100644 tests/render/fixtures/pymd_snippet.md

diff --git a/tests/format/fixtures/pymd_snippet.md b/tests/format/fixtures/pymd_snippet.md
new file mode 100644
index 0000000..8abc74d
--- /dev/null
+++ b/tests/format/fixtures/pymd_snippet.md
@@ -0,0 +1,33 @@
+pymdown snippets (https://github.com/KyleKing/mdformat-mkdocs/issues/34)
+.
+# Snippets
+
+--8<-- "filename.ext"
+
+--8<-- "; skip.md"
+
+
+--8<--
+filename.md
+filename.log
+--8<--
+
+Content of file A.
+
+Content of file B.
+.
+# Snippets
+
+--8<-- "filename.ext"
+
+--8<-- "; skip.md"
+
+--8<--
+filename.md
+filename.log
+--8<--
+
+Content of file A.
+
+Content of file B.
+.
diff --git a/tests/format/fixtures/text.md b/tests/format/fixtures/text.md
index 7f74b63..a262014 100644
--- a/tests/format/fixtures/text.md
+++ b/tests/format/fixtures/text.md
@@ -1714,38 +1714,3 @@ Support inline bulleted code (https://github.com/KyleKing/mdformat-mkdocs/issues
           iex (new-object net.webclient).DownloadString('https://get.scoop.sh')
           ```
 .
-
-pymdown snippets (https://github.com/KyleKing/mdformat-mkdocs/issues/34)
-.
-# Snippets
-
---8<-- "filename.ext"
-
---8<-- "; skip.md"
-
-
---8<--
-filename.md
-filename.log
---8<--
-
-Content of file A.
-
-Content of file B.
-.
-# Snippets
-
---8<-- "filename.ext"
-
---8<-- "; skip.md"
-
-
---8<--
-filename.md
-filename.log
---8<--
-
-Content of file A.
-
-Content of file B.
-.
diff --git a/tests/format/test_format.py b/tests/format/test_format.py
index eeef244..f013755 100644
--- a/tests/format/test_format.py
+++ b/tests/format/test_format.py
@@ -24,6 +24,7 @@ def flatten(nested_list: list[list[T]]) -> list[T]:
             "material_content_tabs.md",
             "mkdocstrings_autorefs.md",
             "pymd_abbreviations.md",
+            "pymd_snippet.md",
             "text.md",
         )
     ],
diff --git a/tests/render/fixtures/matieral_admonitions.md b/tests/render/fixtures/material_admonitions.md
similarity index 100%
rename from tests/render/fixtures/matieral_admonitions.md
rename to tests/render/fixtures/material_admonitions.md
diff --git a/tests/render/fixtures/pymd_snippet.md b/tests/render/fixtures/pymd_snippet.md
new file mode 100644
index 0000000..3945d0d
--- /dev/null
+++ b/tests/render/fixtures/pymd_snippet.md
@@ -0,0 +1,19 @@
+pymdown snippets (https://github.com/KyleKing/mdformat-mkdocs/issues/34)
+.
+# Snippets
+
+--8<-- "filename.ext"
+
+--8<-- "; skip.md"
+
+
+--8<--
+filename.md
+filename.log
+--8<--
+
+Content of file A.
+
+Content of file B.
+.
+.
diff --git a/tests/render/test_render.py b/tests/render/test_render.py
index 3842902..068ff75 100644
--- a/tests/render/test_render.py
+++ b/tests/render/test_render.py
@@ -23,7 +23,7 @@ def with_plugin(filename, plugins):
 @pytest.mark.parametrize(
     ("line", "title", "text", "expected", "plugins"),
     [
-        *with_plugin("matieral_admonitions.md", [material_admon_plugin]),
+        *with_plugin("material_admonitions.md", [material_admon_plugin]),
         *with_plugin(
             "material_content_tabs.md",
             [material_admon_plugin, material_content_tabs_plugin],

From a387db830cc5fb1557b8f65708064a5e7bec5a6b Mon Sep 17 00:00:00 2001
From: Kyle King <KyleKing@users.noreply.github.com>
Date: Mon, 16 Dec 2024 20:19:58 -0500
Subject: [PATCH 4/6] fix: handle multi-line snippets

---
 mdformat_mkdocs/mdit_plugins/_pymd_snippet.py | 35 +++++++++++++------
 tests/render/fixtures/pymd_snippet.md         |  9 +++++
 tests/render/test_render.py                   |  5 +++
 3 files changed, 39 insertions(+), 10 deletions(-)

diff --git a/mdformat_mkdocs/mdit_plugins/_pymd_snippet.py b/mdformat_mkdocs/mdit_plugins/_pymd_snippet.py
index 559ad6e..b0b4c85 100644
--- a/mdformat_mkdocs/mdit_plugins/_pymd_snippet.py
+++ b/mdformat_mkdocs/mdit_plugins/_pymd_snippet.py
@@ -20,18 +20,16 @@
 
 from mdformat_mkdocs._synced.admon_factories import new_token
 
-# _SNIPPET_MARKER = "--8<--"
-_ABBREVIATION_PATTERN = re.compile(
-    r"--8<-- (?P<label>.+)",
-)
+_SNIPPET_MARKER = "--8<--"
+_ABBREVIATION_PATTERN = re.compile(rf"^{_SNIPPET_MARKER}(?P<label>.*)")
 PYMD_SNIPPET_PREFIX = "pymd_snippet"
 
 
-def _new_match(state: StateBlock, start_line: int) -> re.Match[str] | None:
-    """Determine match between start and end lines."""
+def _content(state: StateBlock, start_line: int) -> str:
+    """Content."""
     start = state.bMarks[start_line] + state.tShift[start_line]
     maximum = state.eMarks[start_line]
-    return _ABBREVIATION_PATTERN.match(state.src[start:maximum])
+    return state.src[start:maximum]
 
 
 def _pymd_snippet(
@@ -43,18 +41,35 @@ def _pymd_snippet(
     if is_code_block(state, start_line):
         return False
 
-    match = _new_match(state, start_line)
+    match = _ABBREVIATION_PATTERN.match(_content(state, start_line))
     if match is None:
         return False
 
     if silent:
         return True
 
-    max_line = start_line
+    max_line = start_line + 1
+    inline = f"{_SNIPPET_MARKER}{match['label']}"
+
+    if not match["label"]:
+        max_search = 20  # Upper limit of lines to search for multi-line snippet
+        current_line = start_line + 1
+        inner = []
+        while (current_line - start_line) < max_search:
+            if max_line == end_line:
+                break  # no 'label'
+            line = _content(state, current_line)
+            if match := _ABBREVIATION_PATTERN.match(line):
+                max_line = current_line + 1
+                inline = "\n".join([_SNIPPET_MARKER, *inner, _SNIPPET_MARKER])
+                break
+            if line:
+                inner.append(line)
+            current_line += 1
 
     with new_token(state, PYMD_SNIPPET_PREFIX, "p"):
         tkn_inline = state.push("inline", "", 0)
-        tkn_inline.content = match["label"]
+        tkn_inline.content = inline
         tkn_inline.map = [start_line, max_line]
         tkn_inline.children = []
 
diff --git a/tests/render/fixtures/pymd_snippet.md b/tests/render/fixtures/pymd_snippet.md
index 3945d0d..b748265 100644
--- a/tests/render/fixtures/pymd_snippet.md
+++ b/tests/render/fixtures/pymd_snippet.md
@@ -16,4 +16,13 @@ Content of file A.
 
 Content of file B.
 .
+<h1>Snippets</h1>
+<p>--8&lt;-- &quot;filename.ext&quot;</p>
+<p>--8&lt;-- &quot;; skip.md&quot;</p>
+<p>--8&lt;--
+filename.md
+filename.log
+--8&lt;--</p>
+<p>Content of file A.</p>
+<p>Content of file B.</p>
 .
diff --git a/tests/render/test_render.py b/tests/render/test_render.py
index 068ff75..22af103 100644
--- a/tests/render/test_render.py
+++ b/tests/render/test_render.py
@@ -10,6 +10,7 @@
     mkdocstrings_autorefs_plugin,
     mkdocstrings_crossreference_plugin,
     pymd_abbreviations_plugin,
+    pymd_snippet_plugin,
 )
 from tests.helpers import print_text
 
@@ -34,6 +35,10 @@ def with_plugin(filename, plugins):
             "mkdocstrings_crossreference.md",
             [mkdocstrings_crossreference_plugin],
         ),
+        *with_plugin(
+            "pymd_snippet.md",
+            [pymd_snippet_plugin],
+        ),
     ],
 )
 def test_render(line, title, text, expected, plugins):

From f38e16ff8255942d8b9c8a536f1b01fdb3459f90 Mon Sep 17 00:00:00 2001
From: Kyle King <KyleKing@users.noreply.github.com>
Date: Mon, 16 Dec 2024 20:25:40 -0500
Subject: [PATCH 5/6] refactor: extract while loop

---
 mdformat_mkdocs/mdit_plugins/_pymd_snippet.py | 43 ++++++++++++-------
 1 file changed, 28 insertions(+), 15 deletions(-)

diff --git a/mdformat_mkdocs/mdit_plugins/_pymd_snippet.py b/mdformat_mkdocs/mdit_plugins/_pymd_snippet.py
index b0b4c85..f70f1e2 100644
--- a/mdformat_mkdocs/mdit_plugins/_pymd_snippet.py
+++ b/mdformat_mkdocs/mdit_plugins/_pymd_snippet.py
@@ -22,6 +22,7 @@
 
 _SNIPPET_MARKER = "--8<--"
 _ABBREVIATION_PATTERN = re.compile(rf"^{_SNIPPET_MARKER}(?P<label>.*)")
+
 PYMD_SNIPPET_PREFIX = "pymd_snippet"
 
 
@@ -32,34 +33,25 @@ def _content(state: StateBlock, start_line: int) -> str:
     return state.src[start:maximum]
 
 
-def _pymd_snippet(
+def _parse(
     state: StateBlock,
+    match: re.Match[str],
     start_line: int,
     end_line: int,
-    silent: bool,
-) -> bool:
-    if is_code_block(state, start_line):
-        return False
-
-    match = _ABBREVIATION_PATTERN.match(_content(state, start_line))
-    if match is None:
-        return False
-
-    if silent:
-        return True
-
+) -> tuple[int, str]:
+    """Return the max line and matched content."""
     max_line = start_line + 1
     inline = f"{_SNIPPET_MARKER}{match['label']}"
 
     if not match["label"]:
         max_search = 20  # Upper limit of lines to search for multi-line snippet
         current_line = start_line + 1
-        inner = []
+        inner: list[str] = []
         while (current_line - start_line) < max_search:
             if max_line == end_line:
                 break  # no 'label'
             line = _content(state, current_line)
-            if match := _ABBREVIATION_PATTERN.match(line):
+            if _ABBREVIATION_PATTERN.match(line):
                 max_line = current_line + 1
                 inline = "\n".join([_SNIPPET_MARKER, *inner, _SNIPPET_MARKER])
                 break
@@ -67,6 +59,27 @@ def _pymd_snippet(
                 inner.append(line)
             current_line += 1
 
+    return max_line, inline
+
+
+def _pymd_snippet(
+    state: StateBlock,
+    start_line: int,
+    end_line: int,
+    silent: bool,
+) -> bool:
+    if is_code_block(state, start_line):
+        return False
+
+    match = _ABBREVIATION_PATTERN.match(_content(state, start_line))
+    if match is None:
+        return False
+
+    if silent:
+        return True
+
+    max_line, inline = _parse(state, match, start_line, end_line)
+
     with new_token(state, PYMD_SNIPPET_PREFIX, "p"):
         tkn_inline = state.push("inline", "", 0)
         tkn_inline.content = inline

From 157750efeb38f675775e376256e3e4096b6bab69 Mon Sep 17 00:00:00 2001
From: Kyle King <KyleKing@users.noreply.github.com>
Date: Mon, 16 Dec 2024 20:40:33 -0500
Subject: [PATCH 6/6] docs: clarify limitations of pymd-snippets

---
 README.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 9b54e88..c8cf657 100644
--- a/README.md
+++ b/README.md
@@ -15,13 +15,16 @@ Supports:
     - *Note*: when specifying `--align-semantic-breaks-in-lists`, the nested indent for ordered lists is three, but is otherwise a multiple of four
 - Unordered list bullets are converted to dashes (`-`) instead of `*`
 - By default, ordered lists are standardized on a single digit (`1.` or `0.`) unless `--number` is specified, then `mdformat-mkdocs` will apply consecutive numbering to ordered lists [for consistency with `mdformat`](https://github.com/executablebooks/mdformat?tab=readme-ov-file#options)
-- [MkDocs-Material Admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions)
+- [MkDocs-Material Admonitions\*](https://squidfunk.github.io/mkdocs-material/reference/admonitions)
+    - \*Note: `mdformat-admon` will format the same admonitions, but for consistency with the mkdocs styleguide, an extra space will be added by this package ([#22](https://github.com/KyleKing/mdformat-admon/pull/22))
 - [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.
 - [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)
     - \*Note: the markup (HTML) rendered for abbreviations is not useful for rendering. If important, I'm open to contributions because the implementation could be challenging
+- [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
 
 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)