fix: add compatibility with mkdocstrings

mkquartodocs/extension.py

@@ -434,12 +434,21 @@ def run(self, lines):
                 cursor = cursor.advance_line(1)
 
         if any(x.startswith(":::") for x in outs):
-            # the ':::' is used in quarto to denote blocks but also used in
-            # mkdocstrings as a special 'domain-specific-syntax' ... so we need
-            # to remove them .... it also points to a bug in the preprocessor
-            # that let them go through ...
-            bads = [x for x in outs if x.startswith(":::")]
-            raise ValueError(f"Cell data contains admonition: {bads}")
+            # Check if these are unprocessed Quarto cell blocks (which would be a bug)
+            # vs. mkdocstrings syntax or other valid uses of ::: (which should be allowed)
+            potential_bugs = []
+            for x in outs:
+                if x.startswith(":::"):
+                    # Check if it looks like Quarto cell syntax that escaped processing
+                    if (
+                        CELL_REGEX.match(x)
+                        or CELL_ELEM_REGEX.match(x)
+                        or CELL_ELEM_ALT_REGEX.match(x)
+                    ):
+                        potential_bugs.append(x)
+
+            if potential_bugs:
+                raise ValueError(f"Unprocessed Quarto cell syntax found: {potential_bugs}")
         return outs
 
 

tests/data/docs_issue69/docs/example.qmd

@@ -0,0 +1,11 @@
+---
+title: Example Quarto Document
+---
+
+# Example
+
+This is a simple quarto document.
+
+```{python}
+print("Hello from Quarto!")
+```

tests/data/docs_issue69/docs/index.md

@@ -0,0 +1,7 @@
+# Test for Issue #69
+
+This is a regular markdown file with mkdocstrings syntax.
+
+::: pathlib.Path
+
+The above line uses mkdocstrings syntax to document the pathlib.Path class.

tests/data/docs_issue69/expected_missing.txt

@@ -0,0 +1,2 @@
+# The example.md generated from example.qmd should be cleaned up
+./docs/example.md

tests/data/docs_issue69/expected_output.txt

@@ -0,0 +1,14 @@
+# Input files
+./mkdocs.yml
+./expected_output.txt
+./expected_missing.txt
+./docs
+./docs/index.md
+./docs/example.qmd
+
+# Site files
+./site/404.html
+./site/index.html
+./site/example/index.html
+./site/sitemap.xml
+./site/sitemap.xml.gz

tests/data/docs_issue69/mkdocs.yml

@@ -0,0 +1,7 @@
+site_name: Issue69 Test
+plugins:
+  - mkquartodocs
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [.]

tests/test_preprocessor.py

@@ -115,3 +115,34 @@ def test_conversion_file(document):
         else:
             msg += ", For extra information set MKQUARTODOCS_TEST_DEBUG_OUT_DIR=1"
         raise AssertionError(msg)
+
+
+def test_issue69_mkdocstrings_syntax():
+    """Test that mkdocstrings syntax (::: prefix) is allowed.
+
+    This is issue #69: https://github.com/jspaezp/mkquartodocs/issues/69
+    The preprocessor should allow mkdocstrings syntax (which doesn't match
+    Quarto cell patterns) to pass through unchanged.
+    """
+    preprocessor = AdmotionCellDataPreprocessor()
+
+    # Markdown with mkdocstrings syntax
+    mkdocstrings_input = [
+        "# API Documentation",
+        "",
+        "::: foo.main.hello",
+        "",
+        "This uses mkdocstrings syntax.",
+        "",
+        "::: another.module.function",
+    ]
+
+    # This should NOT raise an error - mkdocstrings syntax should pass through
+    output = preprocessor.run(mkdocstrings_input)
+
+    # The mkdocstrings lines should be preserved unchanged
+    assert "::: foo.main.hello" in output
+    assert "::: another.module.function" in output
+
+    # Verify the output structure is preserved
+    assert len([line for line in output if line.startswith(":::")]) == 2