mkdocs-markdoc 0.1.0__tar.gz

mkdocs_markdoc-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Node
+node_modules/
+
+# MkDocs built output
+example/site/
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+*.swp

mkdocs_markdoc-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: mkdocs-markdoc
+Version: 0.1.0
+Summary: MkDocs plugin that renders pages with Stripe's Markdoc instead of Python-Markdown
+License: MIT
+Keywords: documentation,markdoc,markdown,mkdocs,plugin
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.9
+Requires-Dist: mkdocs>=1.5
+Provides-Extra: dev
+Requires-Dist: pytest-mock>=3; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mkdocs-markdoc
+
+An MkDocs plugin that completely replaces the default Python-Markdown renderer
+with **[Stripe's Markdoc](https://markdoc.dev)**.  Every `.md` page in your
+docs site is parsed and rendered by Markdoc's HTML renderer — no React
+required.
+
+---
+
+## How it works
+
+```
+MkDocs  ──on_page_markdown──▶  plugin.py  ──stdin──▶  markdoc_runner.js
+                                                              │
+                         HTML string  ◀──stdout──────────────┘
+```
+
+The Python plugin hooks into `on_page_markdown`, pipes the raw Markdown to a
+bundled Node.js script via `subprocess`, and returns the HTML string that
+MkDocs injects into the theme template.
+
+---
+
+## Prerequisites
+
+| Requirement | Minimum version |
+|-------------|----------------|
+| Python      | 3.9             |
+| MkDocs      | 1.5             |
+| Node.js     | 18 LTS          |
+| npm         | 8               |
+
+---
+
+## Installation
+
+### 1 — Install the Python package
+
+```bash
+# From the repo root (editable/development install)
+pip install -e .
+
+# Or once published to PyPI
+pip install mkdocs-markdoc
+```
+
+### 2 — Install the Node.js Markdoc library
+
+The `@markdoc/markdoc` npm package must be resolvable by Node.js when it runs
+the bundled `markdoc_runner.js` script.  Install it in **one** of these
+locations (Node's module resolution will find it):
+
+```bash
+# Option A – global install (simplest for local dev / CI)
+npm install -g @markdoc/markdoc
+
+# Option B – local install in your docs project root
+cd /path/to/your/docs-project
+npm install @markdoc/markdoc
+```
+
+### 3 — Enable the plugin in `mkdocs.yml`
+
+```yaml
+# mkdocs.yml
+site_name: My Docs
+
+plugins:
+  - markdoc          # ← add this; remove or comment out the default 'search'
+                     #   plugin only if you no longer need it
+```
+
+> **Note:** MkDocs' built-in `search` plugin is independent of the Markdown
+> renderer and can be kept alongside `markdoc`:
+> ```yaml
+> plugins:
+>   - search
+>   - markdoc
+> ```
+
+---
+
+## Configuration options
+
+All options are optional.
+
+```yaml
+plugins:
+  - markdoc:
+      # Path to the Node.js executable.
+      # Default: "node"  (resolved via $PATH)
+      node_path: /usr/local/bin/node
+
+      # Path to a JS or JSON file that exports a Markdoc config object.
+      # When omitted, Markdoc uses its built-in defaults (standard Markdown
+      # nodes, no custom tags or functions).
+      markdoc_config: docs/markdoc.config.js
+
+      # Milliseconds to wait for the Node subprocess before raising an error.
+      # Default: 30000  (30 seconds)
+      timeout: 30000
+```
+
+### Example `markdoc.config.js`
+
+```js
+// docs/markdoc.config.js
+const { nodes, Tag } = require("@markdoc/markdoc");
+
+module.exports = {
+  tags: {
+    callout: {
+      render: "div",
+      attributes: {
+        type: { type: String, default: "note" },
+      },
+    },
+  },
+  nodes: {
+    // Override the default heading to add anchor IDs
+    heading: {
+      ...nodes.heading,
+      render: "h1",
+    },
+  },
+};
+```
+
+---
+
+## Running the docs locally
+
+```bash
+mkdocs serve
+```
+
+---
+
+## Caveats & trade-offs
+
+* **Markdoc syntax differs from CommonMark.** Markdoc is a superset of
+  Markdown, but some edge-cases render differently.  Review the
+  [Markdoc syntax reference](https://markdoc.dev/docs/syntax) when migrating
+  an existing docs site.
+* **Node.js subprocess overhead.** Each page spawns (and immediately exits) one
+  Node process.  For large sites with hundreds of pages the build time will
+  increase compared to the native Python-Markdown renderer.  If this becomes a
+  bottleneck, consider batching pages in a future version.
+* **MkDocs extensions are bypassed.** Because we skip Python-Markdown entirely,
+  any `markdown_extensions:` listed in `mkdocs.yml` will have no effect.
+  Equivalent behaviour must be implemented via Markdoc tags/nodes/functions.

mkdocs_markdoc-0.1.0/README.md

@@ -0,0 +1,151 @@
+# mkdocs-markdoc
+
+An MkDocs plugin that completely replaces the default Python-Markdown renderer
+with **[Stripe's Markdoc](https://markdoc.dev)**.  Every `.md` page in your
+docs site is parsed and rendered by Markdoc's HTML renderer — no React
+required.
+
+---
+
+## How it works
+
+```
+MkDocs  ──on_page_markdown──▶  plugin.py  ──stdin──▶  markdoc_runner.js
+                                                              │
+                         HTML string  ◀──stdout──────────────┘
+```
+
+The Python plugin hooks into `on_page_markdown`, pipes the raw Markdown to a
+bundled Node.js script via `subprocess`, and returns the HTML string that
+MkDocs injects into the theme template.
+
+---
+
+## Prerequisites
+
+| Requirement | Minimum version |
+|-------------|----------------|
+| Python      | 3.9             |
+| MkDocs      | 1.5             |
+| Node.js     | 18 LTS          |
+| npm         | 8               |
+
+---
+
+## Installation
+
+### 1 — Install the Python package
+
+```bash
+# From the repo root (editable/development install)
+pip install -e .
+
+# Or once published to PyPI
+pip install mkdocs-markdoc
+```
+
+### 2 — Install the Node.js Markdoc library
+
+The `@markdoc/markdoc` npm package must be resolvable by Node.js when it runs
+the bundled `markdoc_runner.js` script.  Install it in **one** of these
+locations (Node's module resolution will find it):
+
+```bash
+# Option A – global install (simplest for local dev / CI)
+npm install -g @markdoc/markdoc
+
+# Option B – local install in your docs project root
+cd /path/to/your/docs-project
+npm install @markdoc/markdoc
+```
+
+### 3 — Enable the plugin in `mkdocs.yml`
+
+```yaml
+# mkdocs.yml
+site_name: My Docs
+
+plugins:
+  - markdoc          # ← add this; remove or comment out the default 'search'
+                     #   plugin only if you no longer need it
+```
+
+> **Note:** MkDocs' built-in `search` plugin is independent of the Markdown
+> renderer and can be kept alongside `markdoc`:
+> ```yaml
+> plugins:
+>   - search
+>   - markdoc
+> ```
+
+---
+
+## Configuration options
+
+All options are optional.
+
+```yaml
+plugins:
+  - markdoc:
+      # Path to the Node.js executable.
+      # Default: "node"  (resolved via $PATH)
+      node_path: /usr/local/bin/node
+
+      # Path to a JS or JSON file that exports a Markdoc config object.
+      # When omitted, Markdoc uses its built-in defaults (standard Markdown
+      # nodes, no custom tags or functions).
+      markdoc_config: docs/markdoc.config.js
+
+      # Milliseconds to wait for the Node subprocess before raising an error.
+      # Default: 30000  (30 seconds)
+      timeout: 30000
+```
+
+### Example `markdoc.config.js`
+
+```js
+// docs/markdoc.config.js
+const { nodes, Tag } = require("@markdoc/markdoc");
+
+module.exports = {
+  tags: {
+    callout: {
+      render: "div",
+      attributes: {
+        type: { type: String, default: "note" },
+      },
+    },
+  },
+  nodes: {
+    // Override the default heading to add anchor IDs
+    heading: {
+      ...nodes.heading,
+      render: "h1",
+    },
+  },
+};
+```
+
+---
+
+## Running the docs locally
+
+```bash
+mkdocs serve
+```
+
+---
+
+## Caveats & trade-offs
+
+* **Markdoc syntax differs from CommonMark.** Markdoc is a superset of
+  Markdown, but some edge-cases render differently.  Review the
+  [Markdoc syntax reference](https://markdoc.dev/docs/syntax) when migrating
+  an existing docs site.
+* **Node.js subprocess overhead.** Each page spawns (and immediately exits) one
+  Node process.  For large sites with hundreds of pages the build time will
+  increase compared to the native Python-Markdown renderer.  If this becomes a
+  bottleneck, consider batching pages in a future version.
+* **MkDocs extensions are bypassed.** Because we skip Python-Markdown entirely,
+  any `markdown_extensions:` listed in `mkdocs.yml` will have no effect.
+  Equivalent behaviour must be implemented via Markdoc tags/nodes/functions.

mkdocs_markdoc-0.1.0/mkdocs_markdoc/__init__.py

@@ -0,0 +1 @@
+# mkdocs-markdoc: MkDocs plugin that renders pages with Stripe's Markdoc

mkdocs_markdoc-0.1.0/mkdocs_markdoc/assets/markdoc.css

@@ -0,0 +1,95 @@
+/*
+ * markdoc.css — styling for elements that Markdoc emits but Material doesn't
+ * cover on its own (badges, details, code block tweaks).
+ *
+ * Most standard HTML elements (headings, tables, blockquotes, lists, etc.)
+ * are already styled by Material's .md-typeset rules because our plugin output
+ * lands inside that wrapper.
+ */
+
+/* -------------------------------------------------------------------------
+ * Code blocks
+ * Our fence override renders <pre><code class="language-X">.
+ * highlight.js adds the `hljs` class; we normalise padding to match Material.
+ * ---------------------------------------------------------------------- */
+
+.md-typeset pre > code.hljs {
+  padding: 1em 1.2em;
+  border-radius: 0.2rem;
+  font-size: 0.85em;
+  line-height: 1.6;
+}
+
+.md-typeset pre {
+  position: relative;
+}
+
+/* -------------------------------------------------------------------------
+ * Admonitions  (callout → Material .admonition markup, styled for free)
+ * ---------------------------------------------------------------------- */
+
+.md-typeset .admonition {
+  margin: 1.5em 0;
+}
+
+/* -------------------------------------------------------------------------
+ * Badge  (inline colored chips)
+ * ---------------------------------------------------------------------- */
+
+.md-typeset .mkd-badge {
+  display: inline-block;
+  padding: 0.1em 0.55em;
+  border-radius: 0.25rem;
+  font-size: 0.72em;
+  font-weight: 700;
+  letter-spacing: 0.02em;
+  line-height: 1.6;
+  vertical-align: middle;
+  white-space: nowrap;
+}
+
+.md-typeset .mkd-badge--blue   { background-color: #1976d2; color: #fff; }
+.md-typeset .mkd-badge--green  { background-color: #388e3c; color: #fff; }
+.md-typeset .mkd-badge--red    { background-color: #d32f2f; color: #fff; }
+.md-typeset .mkd-badge--orange { background-color: #e65100; color: #fff; }
+.md-typeset .mkd-badge--grey   { background-color: #616161; color: #fff; }
+.md-typeset .mkd-badge--purple { background-color: #6a1b9a; color: #fff; }
+
+/* -------------------------------------------------------------------------
+ * Details  (collapsible <details>/<summary>)
+ *
+ * Material for MkDocs already styles all `details > summary` elements with
+ * its own disclosure icon (the right-side chevron) and flex layout. Adding
+ * our own ::before marker on top produces a double-icon overlap and pushes
+ * text mid-word. We therefore only set box-level styles here and let
+ * Material's built-in `details` CSS handle the indicator entirely.
+ * ---------------------------------------------------------------------- */
+
+.md-typeset details.mkd-details {
+  border-left: 4px solid var(--md-primary-fg-color);
+  background-color: var(--md-admonition-bg-color, rgba(68, 138, 255, .05));
+  border-radius: 0.2rem;
+  padding: 0 1em;
+  margin: 1.25em 0;
+}
+
+/* Tighten summary text weight to make it feel like a heading */
+.md-typeset details.mkd-details > summary {
+  font-weight: 600;
+}
+
+/* Separate summary from body when open */
+.md-typeset details.mkd-details[open] > summary {
+  border-bottom: 1px solid var(--md-default-fg-color--lightest);
+  margin-bottom: 0.25em;
+}
+
+/* -------------------------------------------------------------------------
+ * Tables
+ * Markdoc renders plain <table> elements; Material styles them inside
+ * .md-typeset automatically. Enforce full width for consistency.
+ * ---------------------------------------------------------------------- */
+
+.md-typeset table:not([class]) {
+  width: 100%;
+}

mkdocs_markdoc-0.1.0/mkdocs_markdoc/markdoc_runner.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+/**
+ * markdoc_runner.js
+ *
+ * Reads raw Markdown from stdin, renders it to HTML with @markdoc/markdoc,
+ * and writes the HTML to stdout.
+ *
+ * Usage (invoked by the Python plugin):
+ *   echo "# Hello" | node markdoc_runner.js [--config <path>]
+ *
+ * Exit codes:
+ *   0  success – HTML written to stdout
+ *   1  error   – message written to stderr
+ */
+
+"use strict";
+
+const path = require("path");
+const fs = require("fs");
+
+// ---------------------------------------------------------------------------
+// Argument parsing  (minimal – only --config <path> is supported)
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const args = { configPath: null };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === "--config" && argv[i + 1]) {
+      args.configPath = path.resolve(argv[++i]);
+    }
+  }
+  return args;
+}
+
+// ---------------------------------------------------------------------------
+// Load optional Markdoc config
+// ---------------------------------------------------------------------------
+
+function loadMarkdocConfig(configPath) {
+  if (!configPath) return {};
+
+  if (!fs.existsSync(configPath)) {
+    throw new Error(`Markdoc config file not found: ${configPath}`);
+  }
+
+  const ext = path.extname(configPath).toLowerCase();
+
+  if (ext === ".json") {
+    return JSON.parse(fs.readFileSync(configPath, "utf8"));
+  }
+
+  // Treat .js / .cjs as a CommonJS module exporting a config object.
+  // The module may export the config directly or as `module.exports.default`.
+  const mod = require(configPath);
+  return mod.default ?? mod;
+}
+
+// ---------------------------------------------------------------------------
+// Render pipeline
+// ---------------------------------------------------------------------------
+
+function renderMarkdoc(source, markdocConfig) {
+  // Lazy-require so a missing package produces a clear error message.
+  let Markdoc;
+  try {
+    Markdoc = require("@markdoc/markdoc");
+  } catch (err) {
+    throw new Error(
+      "@markdoc/markdoc is not installed. " +
+        "Run `npm install @markdoc/markdoc` in the plugin directory or globally.\n" +
+        err.message
+    );
+  }
+
+  // 1. Parse – produces an AST.
+  const ast = Markdoc.parse(source);
+
+  // 2. Validate – surface any Markdoc schema errors before transforming.
+  const errors = Markdoc.validate(ast, markdocConfig);
+  if (errors.length > 0) {
+    const messages = errors
+      .map((e) => `  [${e.error.level}] ${e.error.message} (line ${e.lines?.[0] ?? "?"})`)
+      .join("\n");
+
+    // Only hard-fail on actual errors; warnings/hints are logged to stderr.
+    const fatal = errors.filter((e) => e.error.level === "error");
+    if (fatal.length > 0) {
+      throw new Error(`Markdoc validation errors:\n${messages}`);
+    }
+
+    process.stderr.write(`mkdocs-markdoc: Markdoc warnings:\n${messages}\n`);
+  }
+
+  // 3. Transform – converts AST to a renderable tree using the config.
+  const renderableTree = Markdoc.transform(ast, markdocConfig);
+
+  // 4. Render to plain HTML (no React dependency).
+  return Markdoc.renderers.html(renderableTree);
+}
+
+// ---------------------------------------------------------------------------
+// Main – read stdin, render, write stdout
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const args = parseArgs(process.argv);
+
+  let markdocConfig;
+  try {
+    markdocConfig = loadMarkdocConfig(args.configPath);
+  } catch (err) {
+    process.stderr.write(`mkdocs-markdoc: failed to load config: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  // Collect stdin into a single string.
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const source = Buffer.concat(chunks.map((c) => Buffer.from(c))).toString("utf8");
+
+  let html;
+  try {
+    html = renderMarkdoc(source, markdocConfig);
+  } catch (err) {
+    process.stderr.write(`mkdocs-markdoc: render error: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  process.stdout.write(html);
+}
+
+main().catch((err) => {
+  process.stderr.write(`mkdocs-markdoc: unexpected error: ${err.message}\n`);
+  process.exit(1);
+});

mkdocs_markdoc-0.1.0/mkdocs_markdoc/plugin.py

@@ -0,0 +1,246 @@
+"""
+MkDocs plugin that replaces the default Python-Markdown renderer with
+Stripe's Markdoc, via a bundled Node.js subprocess.
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+import subprocess
+from html.parser import HTMLParser
+from pathlib import Path
+from typing import Any
+
+from mkdocs.config import config_options
+from mkdocs.config.base import Config
+from mkdocs.plugins import BasePlugin
+from mkdocs.structure.files import File, Files
+from mkdocs.structure.pages import Page
+from mkdocs.structure.toc import AnchorLink, TableOfContents
+
+log = logging.getLogger("mkdocs.plugins.markdoc")
+
+# Absolute path to the bundled Node.js runner so it works regardless of cwd.
+_RUNNER_PATH = Path(__file__).parent / "markdoc_runner.js"
+
+_HEADING_TAGS = frozenset({"h1", "h2", "h3", "h4", "h5", "h6"})
+
+
+class _HeadingParser(HTMLParser):
+    """Extract heading text + existing id attributes from rendered HTML."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.headings: list[dict] = []
+        self._tag: str = ""
+        self._id: str = ""
+        self._text: list[str] = []
+
+    def handle_starttag(self, tag: str, attrs: list) -> None:
+        if tag in _HEADING_TAGS:
+            self._tag = tag
+            self._id = dict(attrs).get("id", "")
+            self._text = []
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag == self._tag and tag in _HEADING_TAGS:
+            self.headings.append({
+                "level": int(self._tag[1]),
+                "id": self._id,
+                "text": "".join(self._text).strip(),
+            })
+            self._tag = ""
+
+    def handle_data(self, data: str) -> None:
+        if self._tag:
+            self._text.append(data)
+
+
+def _toc_from_html(html: str) -> TableOfContents:
+    """
+    Build a MkDocs TableOfContents from <hN id="..."> elements in the HTML.
+
+    The heading node override in markdoc.config.js guarantees every heading
+    already carries an id attribute, so no HTML modification is needed here.
+    Headings without an id (e.g. those inside custom tag blocks that swallow
+    them) are silently skipped.
+    """
+    parser = _HeadingParser()
+    parser.feed(html)
+
+    top: list[AnchorLink] = []
+    stack: list[AnchorLink] = []
+
+    for h in parser.headings:
+        if not h["id"]:
+            continue
+        link = AnchorLink(title=h["text"], id=h["id"], level=h["level"])
+        while stack and stack[-1].level >= h["level"]:
+            stack.pop()
+        if stack:
+            stack[-1].children.append(link)
+        else:
+            top.append(link)
+        stack.append(link)
+
+    return TableOfContents(top)
+
+
+class MarkdocPluginConfig(Config):
+    # Path to the `node` executable. Defaults to whatever is on $PATH.
+    node_path = config_options.Type(str, default="node")
+
+    # Optional: path to a Markdoc config JS/JSON file that the runner will
+    # `require()`. When empty the runner uses bare Markdoc defaults.
+    markdoc_config = config_options.Optional(config_options.File(exists=True))
+
+    # Milliseconds before the Node subprocess is killed and an error raised.
+    timeout = config_options.Type(int, default=30_000)
+
+
+class MarkdocPlugin(BasePlugin[MarkdocPluginConfig]):
+    """
+    Intercepts raw Markdown on every page and hands it to the Node.js Markdoc
+    runner.  The runner returns a plain HTML string that MkDocs then injects
+    into its theme template exactly as it would with the normal renderer.
+
+    Lifecycle
+    ---------
+    on_config  – validate that Node.js is available once, up front.
+    on_page_markdown – convert each page's Markdown to HTML via subprocess.
+    """
+
+    def on_config(self, config: dict[str, Any]) -> dict[str, Any]:
+        node_exec = self.config["node_path"]
+
+        # Resolve "node" to a full path so the error message is unambiguous.
+        resolved = shutil.which(node_exec)
+        if resolved is None:
+            raise RuntimeError(
+                f"mkdocs-markdoc: Node.js executable '{node_exec}' not found. "
+                "Install Node.js (https://nodejs.org) or set the `node_path` "
+                "option in your mkdocs.yml plugin configuration."
+            )
+
+        self._node_exec = resolved
+        log.debug("mkdocs-markdoc: using Node.js at %s", resolved)
+
+        # Inject the bundled stylesheet so it loads before any user extra_css.
+        config.setdefault("extra_css", []).insert(0, "assets/markdoc.css")
+
+        # Verify @markdoc/markdoc is installed where the runner can reach it.
+        check = self._run_node(
+            "require('@markdoc/markdoc'); process.stdout.write('ok');"
+        )
+        if check.returncode != 0 or check.stdout.strip() != "ok":
+            stderr = check.stderr.strip()
+            raise RuntimeError(
+                "mkdocs-markdoc: @markdoc/markdoc is not importable from the "
+                "Node.js runner.  Run `npm install @markdoc/markdoc` (globally "
+                f"or in the project directory).\nNode stderr: {stderr}"
+            )
+
+        return config
+
+    def on_files(self, files: Files, config: dict[str, Any], **kwargs: Any) -> Files:
+        """Inject the bundled markdoc.css into the MkDocs file collection."""
+        files.append(File(
+            path="assets/markdoc.css",
+            src_dir=str(Path(__file__).parent),
+            dest_dir=config["site_dir"],
+            use_directory_urls=config["use_directory_urls"],
+        ))
+        return files
+
+    # ------------------------------------------------------------------
+    # Core hook
+    # ------------------------------------------------------------------
+
+    def on_page_markdown(
+        self,
+        markdown: str,
+        page: Page,
+        config: dict[str, Any],
+        **kwargs: Any,
+    ) -> str:
+        """
+        Called by MkDocs with the raw Markdown string for every page.
+        Returns the rendered HTML string.
+        """
+        try:
+            result = self._run_node_runner(markdown)
+        except FileNotFoundError:
+            # Node executable disappeared between on_config and now.
+            raise RuntimeError(
+                f"mkdocs-markdoc: Node.js executable '{self._node_exec}' "
+                "disappeared during the build."
+            )
+        except subprocess.TimeoutExpired:
+            raise RuntimeError(
+                f"mkdocs-markdoc: Node.js subprocess timed out after "
+                f"{self.config['timeout']} ms while processing "
+                f"'{page.file.src_path}'."
+            )
+
+        if result.returncode != 0:
+            stderr = result.stderr.strip()
+            raise RuntimeError(
+                f"mkdocs-markdoc: Markdoc rendering failed for "
+                f"'{page.file.src_path}'.\nNode stderr: {stderr}"
+            )
+
+        html = result.stdout
+        if not html:
+            log.warning(
+                "mkdocs-markdoc: empty HTML output for '%s' – "
+                "returning empty string.",
+                page.file.src_path,
+            )
+
+        return html
+
+    def on_page_content(
+        self,
+        html: str,
+        page: Page,
+        config: dict[str, Any],
+        **kwargs: Any,
+    ) -> str:
+        """
+        Called by MkDocs after Python-Markdown has processed the page.
+
+        Because we bypass Python-Markdown entirely, page.toc is empty after
+        page.render() — the toc extension never sees any Markdown headings.
+        We rebuild it here by parsing the id-annotated <hN> elements that
+        the heading node override in markdoc.config.js already produced.
+        """
+        page.toc = _toc_from_html(html)
+        return html
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _run_node_runner(self, markdown: str) -> subprocess.CompletedProcess:
+        """Pipe *markdown* into markdoc_runner.js and return the result."""
+        cmd = [self._node_exec, str(_RUNNER_PATH)]
+        if self.config["markdoc_config"]:
+            cmd += ["--config", self.config["markdoc_config"]]
+
+        return subprocess.run(
+            cmd,
+            input=markdown,
+            capture_output=True,
+            text=True,
+            timeout=self.config["timeout"] / 1000,  # subprocess uses seconds
+        )
+
+    def _run_node(self, script: str) -> subprocess.CompletedProcess:
+        """Run an inline Node.js *script* string for quick checks."""
+        return subprocess.run(
+            [self._node_exec, "-e", script],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )

mkdocs_markdoc-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mkdocs-markdoc"
+version = "0.1.0"
+description = "MkDocs plugin that renders pages with Stripe's Markdoc instead of Python-Markdown"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+keywords = ["mkdocs", "markdoc", "markdown", "plugin", "documentation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Documentation",
+    "Topic :: Software Development :: Documentation",
+]
+dependencies = [
+    "mkdocs>=1.5",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "pytest-mock>=3",
+]
+
+[project.entry-points."mkdocs.plugins"]
+markdoc = "mkdocs_markdoc.plugin:MarkdocPlugin"
+
+# ---------------------------------------------------------------------------
+# Hatch build – make sure the JS runner is included in the wheel/sdist.
+# ---------------------------------------------------------------------------
+
+[tool.hatch.build.targets.wheel]
+packages = ["mkdocs_markdoc"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "mkdocs_markdoc/**",
+    "README.md",
+    "pyproject.toml",
+]
+
+# ---------------------------------------------------------------------------
+# Ruff (optional – only applied when ruff is installed)
+# ---------------------------------------------------------------------------
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"