mdmint 0.2.0__py3-none-any.whl

mdmint/render.py

@@ -0,0 +1,343 @@
+"""Markdown → HTML body, using markdown-it-py and a handful of plugins.
+
+This is the single intermediate representation feeding both the DOCX and PDF
+writers. Mermaid fences and LaTeX math are routed through the optional renderers
+(:mod:`mdmint.mermaid`, :mod:`mdmint.mathrender`) via custom render rules; the work
+directory they write images into is threaded through markdown-it's ``env``.
+"""
+
+from __future__ import annotations
+
+import html
+import re
+import unicodedata
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Optional, cast
+
+from markdown_it import MarkdownIt
+from mdit_py_plugins.admon import admon_plugin
+from mdit_py_plugins.anchors import anchors_plugin
+from mdit_py_plugins.dollarmath import dollarmath_plugin
+from mdit_py_plugins.footnote import footnote_plugin
+from mdit_py_plugins.front_matter import front_matter_plugin
+from mdit_py_plugins.tasklists import tasklists_plugin
+
+from . import admonitions, mathrender, mermaid
+
+if TYPE_CHECKING:
+    from markdown_it.renderer import RendererHTML
+    from markdown_it.rules_core import StateCore
+    from markdown_it.token import Token
+    from markdown_it.utils import EnvType, OptionsDict
+
+# A heading as (level, text, anchor id or None).
+Heading = tuple[int, str, Optional[str]]
+
+_TOC_MARKER = re.compile(r"<p>\[\[?TOC\]\]?</p>", re.IGNORECASE)
+
+# Trailing attr_list on a heading, python-markdown / mkdocs style:
+# ``# Title {#custom-id .part}`` or ``# Title {: .appendix }``.
+_HEADING_ATTRS = re.compile(r"\s*\{:?\s*((?:[#.][\w-]+\s*)+)\}\s*$")
+
+
+def slugify(title: str) -> str:
+    """Heading id slug compatible with mkdocs' default ``toc`` slugify.
+
+    Matching mkdocs matters because docs written for it link to headings by these
+    ids (``page.md#2-the-maintenance-case``). Non-ASCII is folded away as mkdocs
+    does; a heading with nothing ASCII left keeps its Unicode word characters so it
+    still gets a usable id.
+    """
+    ascii_ = unicodedata.normalize("NFKD", title).encode("ascii", "ignore").decode("ascii")
+    for value in (ascii_, title):
+        value = re.sub(r"[^\w\s-]", "", value).strip().lower()
+        value = re.sub(r"[-\s]+", "-", value)
+        if value:
+            return value
+    return "section"
+
+
+def _heading_attrs_strip(state: StateCore) -> None:
+    """Core rule (before anchors): strip a trailing ``{#id .class}`` from headings.
+
+    The attrs are parked in ``token.meta`` so the slug is computed from the clean
+    title, then re-applied by :func:`_heading_attrs_apply` after the anchors rule
+    (which would otherwise overwrite a custom id).
+    """
+    tokens = state.tokens
+    for i, tok in enumerate(tokens):
+        if tok.type != "heading_open" or i + 1 >= len(tokens):
+            continue
+        inline = tokens[i + 1]
+        last = inline.children[-1] if inline.children else None
+        if last is None or last.type != "text":
+            continue
+        m = _HEADING_ATTRS.search(last.content)
+        if not m:
+            continue
+        last.content = last.content[: m.start()]
+        inline.content = _HEADING_ATTRS.sub("", inline.content)
+        parts = m.group(1).split()
+        tok.meta = dict(tok.meta or {})
+        tok.meta["attr_id"] = next((p[1:] for p in parts if p.startswith("#")), None)
+        tok.meta["attr_classes"] = [p[1:] for p in parts if p.startswith(".")]
+
+
+def _heading_attrs_apply(state: StateCore) -> None:
+    for tok in state.tokens:
+        if tok.type != "heading_open" or not tok.meta:
+            continue
+        if tok.meta.get("attr_id"):
+            tok.attrSet("id", tok.meta["attr_id"])
+        if tok.meta.get("attr_classes"):
+            tok.attrSet("class", " ".join(tok.meta["attr_classes"]))
+
+
+def _math_inline(tokens: Sequence[Token], idx: int, options: OptionsDict, env: EnvType) -> str:
+    return mathrender.render(tokens[idx].content, block=False, work_dir=env["work_dir"])
+
+
+def _math_block(tokens: Sequence[Token], idx: int, options: OptionsDict, env: EnvType) -> str:
+    return mathrender.render(tokens[idx].content, block=True, work_dir=env["work_dir"])
+
+
+# --- Admonitions (!!! / ??? callouts) -------------------------------------
+#
+# We render each admonition as a full-width single-cell table rather than the
+# plugin's default <div>. A <div> with CSS looks right in PDF but htmldocx drops
+# it entirely (no CSS, no box); a one-cell table is the one structure both
+# writers turn into a real box. The dynamic per-type colours go inline so the PDF
+# backend needs no generated stylesheet, and the accent-coloured title doubles as
+# the marker the DOCX post-pass keys on (see backends._style_admonitions).
+
+
+def _admonition_open(tokens: Sequence[Token], idx: int, options: OptionsDict, env: EnvType) -> str:
+    tok = tokens[idx]
+    tag = (tok.meta or {}).get("tag", "")
+    canon = admonitions.resolve(tag)
+    accent, bg = admonitions.style_for(tag)
+    env.setdefault("_admon_stack", []).append((accent, bg))
+    classes = tok.attrGet("class") or f"admonition {canon}"
+    return (
+        f'<table class="{classes}"><tbody><tr>'
+        f'<td class="admonition-cell" style="background-color:{bg};'
+        f'border-left:4px solid {accent};">'
+    )
+
+
+def _admonition_close(tokens: Sequence[Token], idx: int, options: OptionsDict, env: EnvType) -> str:
+    stack = env.get("_admon_stack")
+    if stack:
+        stack.pop()
+    return "</td></tr></tbody></table>\n"
+
+
+def _admonition_title_open(
+    tokens: Sequence[Token], idx: int, options: OptionsDict, env: EnvType
+) -> str:
+    stack = env.get("_admon_stack") or [admonitions.style_for("note")]
+    accent = stack[-1][0]
+    # The colour must live on a <span> (not the <p>): htmldocx only copies run
+    # colour from a span's inline style, and that coloured run is exactly what the
+    # DOCX post-pass uses to recognise the admonition.
+    return (
+        f'<p class="admonition-title" style="margin:0 0 0.4em 0;">'
+        f'<span style="color:{accent};"><strong>'
+    )
+
+
+def _admonition_title_close(
+    tokens: Sequence[Token], idx: int, options: OptionsDict, env: EnvType
+) -> str:
+    return "</strong></span></p>\n"
+
+
+def _build_md() -> MarkdownIt:
+    """Construct a configured MarkdownIt instance (stateless across renders)."""
+    md = (
+        MarkdownIt("commonmark", {"html": True, "linkify": True, "typographer": False})
+        .enable(["table", "strikethrough"])
+        .use(front_matter_plugin)  # strip YAML front-matter from output
+        .use(footnote_plugin)
+        .use(tasklists_plugin, enabled=True)
+        .use(anchors_plugin, max_level=6, permalink=False, slug_func=slugify)
+        .use(dollarmath_plugin, double_inline=True)
+        .use(admon_plugin)  # !!! note / ??? collapsible callouts
+    )
+    md.core.ruler.before("anchor", "heading_attrs_strip", _heading_attrs_strip)
+    md.core.ruler.after("anchor", "heading_attrs_apply", _heading_attrs_apply)
+
+    # Renderer rules are called as rule(tokens, idx, options, env): plain functions work.
+    rules: dict[str, Any] = cast("RendererHTML", md.renderer).rules
+
+    # Route mermaid fenced blocks through the optional renderer; everything else
+    # uses the default fence rule.
+    default_fence = rules["fence"]
+
+    def fence(tokens: Sequence[Token], idx: int, options: OptionsDict, env: EnvType) -> str:
+        token = tokens[idx]
+        info = token.info.strip()
+        lang = info.split(maxsplit=1)[0] if info else ""
+        if lang.lower() == "mermaid":
+            return mermaid.render(token.content, env["work_dir"])
+        return default_fence(tokens, idx, options, env)
+
+    rules["fence"] = fence
+
+    # Route math tokens through the optional renderer.
+    rules["math_inline"] = _math_inline
+    rules["math_inline_double"] = _math_block  # $$...$$ used inline
+    rules["math_block"] = _math_block
+    rules["math_block_label"] = _math_block
+
+    # Route admonitions to a styled single-cell table (see helpers above).
+    rules["admonition_open"] = _admonition_open
+    rules["admonition_close"] = _admonition_close
+    rules["admonition_title_open"] = _admonition_title_open
+    rules["admonition_title_close"] = _admonition_title_close
+    return md
+
+
+_MD = _build_md()
+
+
+def _inline_text(inline_token: Token | None) -> str:
+    """Plain-text content of an inline token (for TOC labels)."""
+    if not inline_token or not inline_token.children:
+        return inline_token.content if inline_token else ""
+    return "".join(c.content for c in inline_token.children if c.type in ("text", "code_inline"))
+
+
+def _extract_headings(tokens: Sequence[Token]) -> list[Heading]:
+    """Return (level, text, anchor_id) for every heading in the document."""
+    headings: list[Heading] = []
+    for i, tok in enumerate(tokens):
+        if tok.type == "heading_open":
+            level = int(tok.tag[1])
+            anchor = tok.attrGet("id")
+            text = _inline_text(tokens[i + 1]) if i + 1 < len(tokens) else ""
+            headings.append((level, text, None if anchor is None else str(anchor)))
+    return headings
+
+
+def build_toc(headings: Sequence[Heading]) -> str:
+    """Build a ``<nav class="toc">`` block from a list of (level, text, anchor)."""
+    if not headings:
+        return ""
+    items = []
+    for level, text, anchor in headings:
+        label = html.escape(text)
+        link = f'<a href="#{anchor}">{label}</a>' if anchor else label
+        indent = (level - 1) * 1.2
+        items.append(f'<li style="margin-left:{indent:.1f}em">{link}</li>')
+    return f'<nav class="toc"><div class="toc-title">Contents</div><ul>{"".join(items)}</ul></nav>'
+
+
+def has_toc_marker(body: str) -> bool:
+    return bool(_TOC_MARKER.search(body))
+
+
+def strip_toc_markers(body: str) -> str:
+    """Remove any literal ``[TOC]`` markers from a rendered body."""
+    return _TOC_MARKER.sub("", body)
+
+
+def prefix_anchors(
+    body: str, headings: Sequence[Heading], prefix: str
+) -> tuple[str, list[Heading]]:
+    """Namespace heading anchors so several documents can share one HTML page.
+
+    Returns ``(body, headings)`` with each heading's ``id`` (and the matching TOC
+    anchor) prefixed, so a consolidated TOC over merged files links unambiguously
+    even when two files use the same heading text. Non-heading ids (e.g. footnotes)
+    are left untouched.
+    """
+    mapping: dict[str, str] = {}
+    new_headings: list[Heading] = []
+    for level, text, anchor in headings:
+        if anchor:
+            mapping[anchor] = f"{prefix}{anchor}"
+            new_headings.append((level, text, mapping[anchor]))
+        else:
+            new_headings.append((level, text, anchor))
+    if mapping:
+
+        def repl(m: re.Match[str]) -> str:
+            old = m.group(2)
+            return f"{m.group(1)}{mapping.get(old, old)}{m.group(3)}"
+
+        body = re.sub(r'(\bid=")([^"]*)(")', repl, body)
+    return body, new_headings
+
+
+_HEADING_TAG = re.compile(r"<(/?)h([1-6])(?=[\s>])", re.IGNORECASE)
+_HEADING_HTML = re.compile(r"<h([1-6])\b([^>]*)>(.*?)</h\1>", re.IGNORECASE | re.DOTALL)
+_ID_ATTR = re.compile(r'\bid="([^"]*)"')
+
+
+def shift_headings(body: str, offset: int) -> str:
+    """Demote every heading in *body* by *offset* levels (capped at ``h6``)."""
+    if not offset:
+        return body
+    return _HEADING_TAG.sub(lambda m: f"<{m.group(1)}h{min(6, int(m.group(2)) + offset)}", body)
+
+
+def namespace_ids(body: str, prefix: str) -> str:
+    """Prefix *every* ``id`` and in-page ``href="#..."`` in *body*.
+
+    Unlike :func:`prefix_anchors` (headings only), this also covers footnotes, so
+    several documents stitched into one keep their footnote links apart.
+    """
+    body = re.sub(
+        r'(\bid=")([^"]*)(")', lambda m: f"{m.group(1)}{prefix}{m.group(2)}{m.group(3)}", body
+    )
+    return re.sub(
+        r'(\bhref="#)([^"]+)(")', lambda m: f"{m.group(1)}{prefix}{m.group(2)}{m.group(3)}", body
+    )
+
+
+def headings_from_html(body: str) -> list[Heading]:
+    """Return (level, text, anchor_id) for every heading in an HTML fragment."""
+    out: list[Heading] = []
+    for m in _HEADING_HTML.finditer(body):
+        idm = _ID_ATTR.search(m.group(2))
+        text = html.unescape(re.sub(r"<[^>]+>", "", m.group(3))).strip()
+        out.append((int(m.group(1)), text, idm.group(1) if idm else None))
+    return out
+
+
+def parse(md_text: str, *, work_dir: Path) -> tuple[str, list[Heading]]:
+    """Render Markdown to an HTML fragment and return ``(body, headings)``.
+
+    ``headings`` is a list of (level, text, anchor) in document order. No table of
+    contents is inserted — use :func:`apply_toc` (single file) or :func:`build_toc`
+    (consolidated across merged files).
+    """
+    env: dict[str, Any] = {"work_dir": work_dir}
+    tokens = _MD.parse(md_text, env)
+    body = _MD.renderer.render(tokens, _MD.options, env)
+    return body, _extract_headings(tokens)
+
+
+def apply_toc(body: str, headings: Sequence[Heading], toc: bool) -> str:
+    """Insert a single-document TOC: at a ``[TOC]`` marker if present, else at the
+    top when *toc* is True. A stray marker with no TOC wanted is dropped."""
+    toc_html = build_toc(headings)
+    if toc_html and _TOC_MARKER.search(body):
+        return _TOC_MARKER.sub(toc_html, body, count=1)
+    if toc and toc_html:
+        return toc_html + "\n" + body
+    if _TOC_MARKER.search(body):
+        return _TOC_MARKER.sub("", body)
+    return body
+
+
+def render_body(md_text: str, *, work_dir: Path, toc: bool = False) -> str:
+    """Render Markdown source to an HTML fragment (no <html>/<body> wrapper).
+
+    toc: if True, insert a table of contents at the top (unless a ``[TOC]`` marker
+         is present, in which case it is inserted there regardless of this flag).
+    """
+    body, headings = parse(md_text, work_dir=work_dir)
+    return apply_toc(body, headings, toc)

mdmint/resources/default.css

@@ -0,0 +1,122 @@
+/* Base styling shared by the PDF and (where supported) DOCX writers.
+   Kept deliberately simple: xhtml2pdf supports only a subset of CSS, so we avoid
+   flexbox/grid and stick to properties it understands (margins, borders, fonts,
+   page breaks). weasyprint honours all of it and a bit more. */
+
+@page {
+    size: a4;
+    margin: 2cm;
+}
+
+body {
+    font-family: "Helvetica", "Arial", sans-serif;
+    font-size: 11pt;
+    line-height: 1.45;
+    color: #1a1a1a;
+}
+
+h1, h2, h3, h4, h5, h6 {
+    font-family: "Helvetica", "Arial", sans-serif;
+    color: #111;
+    line-height: 1.2;
+    margin-top: 1.1em;
+    margin-bottom: 0.4em;
+}
+
+h1 { font-size: 22pt; border-bottom: 2px solid #ddd; padding-bottom: 4px; }
+h2 { font-size: 17pt; border-bottom: 1px solid #eee; padding-bottom: 3px; }
+h3 { font-size: 14pt; }
+h4 { font-size: 12pt; }
+
+p { margin: 0.5em 0; }
+
+a { color: #2a6db0; text-decoration: none; }
+
+/* Inline code and code blocks */
+code {
+    font-family: "Courier New", monospace;
+    font-size: 10pt;
+    background-color: #f4f4f4;
+    padding: 1px 3px;
+}
+
+pre {
+    font-family: "Courier New", monospace;
+    font-size: 9.5pt;
+    background-color: #f4f4f4;
+    border: 1px solid #e0e0e0;
+    padding: 8px 10px;
+    margin: 0.6em 0;
+    white-space: pre-wrap;
+    word-wrap: break-word;
+}
+
+pre code { background-color: transparent; padding: 0; }
+
+/* Mermaid fallback block (when no renderer is available) */
+pre.mermaid {
+    background-color: #fff8e6;
+    border: 1px dashed #d4b96a;
+}
+
+blockquote {
+    margin: 0.6em 0;
+    padding: 2px 12px;
+    color: #555;
+    border-left: 4px solid #ddd;
+    background-color: #fafafa;
+}
+
+/* GFM tables */
+table {
+    border-collapse: collapse;
+    margin: 0.7em 0;
+    width: 100%;
+}
+
+th, td {
+    border: 1px solid #ccc;
+    padding: 5px 8px;
+    text-align: left;
+}
+
+th { background-color: #f0f0f0; font-weight: bold; }
+
+img { max-width: 100%; }
+
+/* Math images render inline with the text baseline */
+img.math-inline { vertical-align: middle; }
+img.math-block { display: block; margin: 0.6em auto; }
+
+/* Task lists */
+ul.contains-task-list { list-style-type: none; padding-left: 1em; }
+li.task-list-item { list-style-type: none; }
+
+/* Footnotes */
+hr.footnotes-sep { margin-top: 2em; border: none; border-top: 1px solid #ccc; }
+section.footnotes { font-size: 9.5pt; color: #555; }
+
+/* Table of contents */
+nav.toc { margin: 1em 0 1.5em 0; padding: 8px 12px; border: 1px solid #eee; background: #fafafa; }
+nav.toc .toc-title { font-weight: bold; margin-bottom: 0.4em; }
+nav.toc ul { margin: 0; padding-left: 1.2em; }
+
+/* Admonitions (!!! note / ??? warning callouts).
+   Rendered as a full-width single-cell table; per-type colours (background and
+   the left accent bar) are set inline by the renderer. We only need to undo the
+   generic td border here so the inline accent rule is the sole visible edge. */
+table.admonition { margin: 0.8em 0; }
+table.admonition td.admonition-cell {
+    border: none;          /* generic th,td border off; accent set inline */
+    padding: 6px 12px;
+    vertical-align: top;
+}
+.admonition-title { margin-top: 0; }
+
+/* Page break inserted between merged documents */
+.mdmint-page-break { page-break-before: always; }
+
+/* Part dividers (top-level mkdocs nav sections, or `# Title {.part}`) and
+   appendix chapters (`{.appendix}` / pages under an "Annexes" section). */
+h1.part { page-break-before: always; font-size: 28pt; border-bottom: none; margin-top: 30%; }
+h1.appendix { page-break-before: always; }

mdmint-0.2.0.dist-info/METADATA

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: mdmint
+Version: 0.2.0
+Summary: Export Markdown files to DOCX and/or PDF. Pure-Python, cross-platform, minimal dependencies.
+Author-email: Antonio Olleros <antonio.olleros@meaningfuldata.eu>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/Meaningful-Data/mdmint
+Keywords: markdown,docx,pdf,converter,export,mermaid,mkdocs,template
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: mdit-py-plugins>=0.4
+Requires-Dist: htmldocx>=0.0.6
+Requires-Dist: python-docx>=1.1
+Requires-Dist: xhtml2pdf>=0.2.11
+Requires-Dist: svglib<1.6
+Requires-Dist: PyYAML>=5.1
+Provides-Extra: weasyprint
+Requires-Dist: weasyprint>=60; extra == "weasyprint"
+Provides-Extra: math
+Requires-Dist: matplotlib>=3.5; extra == "math"
+Provides-Extra: all
+Requires-Dist: weasyprint>=60; extra == "all"
+Requires-Dist: matplotlib>=3.5; extra == "all"
+Dynamic: license-file
+
+# mdmint
+
+Export Markdown files to **DOCX** and/or **PDF** — pure-Python, cross-platform,
+minimal dependencies.
+
+A single Markdown → HTML pass feeds both writers. The two features that can't be
+rendered statically in pure Python (mermaid diagrams and LaTeX math) use an
+**optional** renderer if one is available and fall back gracefully otherwise — so
+the base install stays small and works everywhere.
+
+## Install
+
+```bash
+pip install mdmint
+```
+
+The core install is pure-Python (no native libraries):
+`markdown-it-py`, `mdit-py-plugins`, `htmldocx`/`python-docx`, `xhtml2pdf`.
+
+Optional extras:
+
+```bash
+pip install "mdmint[math]"        # render LaTeX math (adds matplotlib)
+pip install "mdmint[weasyprint]"  # higher-fidelity PDF (needs native Pango/Cairo)
+pip install "mdmint[all]"         # both of the above
+```
+
+For **mermaid diagrams**, install the mermaid CLI separately (optional):
+`npm install -g @mermaid-js/mermaid-cli` (provides `mmdc`).
+
+## Usage
+
+```bash
+mdmint notes.md                          # -> notes.pdf
+mdmint notes.md -f docx,pdf -o out/      # both formats into ./out/
+mdmint a.md b.md -f docx                 # -> a.docx and b.docx (one per input)
+mdmint a.md b.md --merge -f pdf -o book.pdf   # one merged PDF
+mdmint report.md --toc -f pdf            # insert a table of contents
+mdmint report.md -f pdf --pdf-backend weasyprint
+```
+
+| Option | Meaning |
+| ------ | ------- |
+| `-f, --format` | `pdf`, `docx`, or both (comma-separated). Default `pdf`. |
+| `-o, --output` | Output directory, or a file path. Default: alongside each input. |
+| `--merge` | With multiple inputs, produce one merged file per format. |
+| `--toc` | Insert a table of contents (or honour a `[TOC]` marker). |
+| `--pdf-backend` | `xhtml2pdf` (default) or `weasyprint`. |
+| `-v, --verbose` | Verbose logging. |
+
+| `--mkdocs FILE` | Build one document from an mkdocs.yml `nav` (instead of INPUTs). |
+| `--section-style` | With `--mkdocs`: `part` (default) or `heading` — see below. |
+| `--template FILE` | Word template (`.docx`/`.dotx`) for DOCX output. |
+| `--meta KEY=VALUE` | Value for a template `{{KEY}}` placeholder (repeatable). |
+| `--style ROLE=STYLE` | Use a specific template style for a role (repeatable). |
+
+Also runnable as `python -m mdmint ...`.
+
+### From an mkdocs site
+
+```bash
+mdmint --mkdocs mkdocs.yml -f docx,pdf -o out/     # -> out/<site_name>.docx/.pdf
+```
+
+The `nav` decides which pages go in and in what order (without a `nav`, the
+`docs_dir` tree is used, like mkdocs does). Sections become headings:
+
+- `--section-style part` (default): a **top-level section** is a *part* divider
+  that doesn't use up a heading level, so its pages keep their `#` as chapters;
+  nested sections become `#`, `##`… and demote their pages to match.
+- `--section-style heading`: every section is a heading one level above its pages.
+
+Pages under a section titled *Annex(es)*, *Appendix* or *Appendices* become
+appendix chapters. Links between pages (`../other/page.md#anchor`) become
+in-document links; links to pages left out of the nav are kept as plain text.
+Headings accept mkdocs `attr_list` syntax (`# Title {#id .part}`).
+
+Settings can live in the mkdocs.yml itself (command-line options win):
+
+```yaml
+extra:
+  mdmint:
+    template: templates/brand.docx     # relative to mkdocs.yml
+    section_style: part
+    status: Final                      # any other key fills {{STATUS}} etc.
+    confidentiality: Internal
+    styles: {code: "My Code Style"}    # optional role overrides
+```
+
+### Branded DOCX with a Word template
+
+```bash
+mdmint report.md -f docx --template brand.docx --meta status=Draft
+```
+
+With `--template`, DOCX output is written *into a copy of the template*: its
+cover, contents page, headers/footers, page setup and styles are kept, and the
+content is appended at the end (or where a paragraph reading `{{CONTENT}}` sits).
+Text like `{{TITLE}}`, `{{AUTHOR}}`, `{{DATE}}` anywhere in the body, headers or
+footers is filled from, in increasing priority: mkdocs.yml (`site_name` → title,
+`site_description` → subtitle, `site_author` → author, `extra.mdmint`), the Markdown
+front matter, and `--meta`. `date` defaults to the current month; placeholders
+left without a value are blanked with a warning.
+
+Each element uses the template's styles, picking the first that exists:
+
+| Role (`--style` key) | Styles tried |
+| --- | --- |
+| headings | `Heading 1`…`Heading N` (deeper levels reuse the last) |
+| `part` / `appendix` | `Part Title` / `Appendix Heading` (else `Heading 1`) |
+| `code` / `inline_code` | `Code Block`, `Source Code`, `HTML Preformatted` / `Inline Code`, `Verbatim Char`, `HTML Code` |
+| `quote` | `Callout`, `Quote` (blockquotes) |
+| `note` / `warning` | `Callout Note` / `Callout Warning` (admonitions, `> [!NOTE]`) |
+| `table` | the template's own (non-stock) table style, else `Table Grid` |
+| `table_heading` / `table_text` | `Table Heading` / `Table Text` |
+| `figure` / `caption` | `Figure` / `Caption` ("Figure N." from the image alt text; `Table: …` before a table gives "Table N.") |
+| lists | `List Bullet`, `List Number` (real multi-level numbering, restarted per list) |
+| footnotes | `Footnote Text`/`Footnote Reference` (created if missing) — real Word footnotes |
+
+How to build a template that styles well — required styles, numbering, placeholders, and a
+specimen file to test it — is in [docs/TEMPLATES.md](docs/TEMPLATES.md).
+
+Headings are bookmarked so in-document links work, and the template's TOC field
+(if any) picks the headings up when Word updates fields on open. Without
+`--template`, DOCX output is unchanged (htmldocx).
+
+### Library API
+
+```python
+from mdmint import convert
+
+convert(["report.md"], formats=["pdf", "docx"], output="out/")
+convert(["a.md", "b.md"], formats=["pdf"], output="book.pdf", merge=True)
+```
+
+## Supported Markdown
+
+CommonMark plus: GFM tables, task lists, strikethrough, footnotes, auto table of
+contents, fenced code, [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/)
+(`!!! note` / `??? warning` callouts), embedded images (relative paths resolved
+against the source file; remote URLs downloaded), LaTeX math, and mermaid diagrams.
+
+## Notes & limitations
+
+- **PDF backend.** `xhtml2pdf` (default) is pure-Python and runs anywhere, with a
+  pragmatic subset of CSS. `weasyprint` produces nicer output but needs native
+  Pango/Cairo libraries, so it is an opt-in extra.
+- **Math** uses matplotlib's *mathtext* engine (a large LaTeX-math subset, no system
+  LaTeX required) rendered to images. Full LaTeX environments (e.g. `align`) are not
+  supported. Without matplotlib, math is shown as literal source with a warning.
+- **Mermaid** requires the `mmdc` CLI. Without it, diagrams are shown as styled code
+  blocks with a warning. A snap-installed `mmdc` is supported (mdmint places its
+  scratch files where snap confinement can read them).
+- **Admonitions** render as a colour-coded callout box (tinted background + accent
+  bar + coloured title) in both PDF and DOCX. Type icons are intentionally omitted:
+  the pure-Python PDF backend can't embed an emoji font, so colour and the title
+  carry the type instead. The collapsible `???`/`???+` blocks render fully expanded
+  (static documents have nothing to collapse into).
+
+## License
+
+Licensed under the [Apache License, Version 2.0](LICENSE).
+
+Copyright 2026 Meaningful Data.

mdmint-0.2.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+mdmint/__init__.py,sha256=H9hgo1y0wS_guc7nOAThErRf7UE2wRIMb87eHtc3MV0,681
+mdmint/__main__.py,sha256=xzZNdhekhaq6aTyyuJjNz7WULBlp61fqqAMHPevfHcs,115
+mdmint/admonitions.py,sha256=nU3WLQOHAifAcJ954IqZRbw2EasQUQQCIteC0J_KxFI,2404
+mdmint/assets.py,sha256=hjgRWZGXYhDyU1I94ta2lZCKkrHGrj-oZN8dKgiOLn8,3003
+mdmint/backends.py,sha256=FgxEaK70Fq2omPXZn7B62DDi1Beglz7UrN-t7VeG9rc,8793
+mdmint/cli.py,sha256=6St1MADS-SY8-ftFd9SLZtudwwMZQOOBIeMKZXxn1Ds,5594
+mdmint/core.py,sha256=Ssai4eIV7jM4HLrHD1jos9CUVFTtcbMe0t4oSev1UDg,15953
+mdmint/docxtemplate.py,sha256=9uayB86si40cb7o79RZ0-J8mccgdv1ifYNg9EIiowJ8,48288
+mdmint/mathrender.py,sha256=Qth_pFfpjuXaUDJCyOlC7MjSyykFubT2F7xx7QIJ8zE,3737
+mdmint/mermaid.py,sha256=u5QlcekW-txs484ouEq-ICQ-5QBN_HLu-9s91aMiypA,5294
+mdmint/mkdocs.py,sha256=3BVwTjoL5BJLZHwCdgQfOpqODU1RtFU1joNSn5xBEG8,12388
+mdmint/render.py,sha256=iGNYH07TIlb-7eAGqWoqcUEZnUtE-gUxo84yQqPclwg,13755
+mdmint/resources/default.css,sha256=hPRWDeJgGXwPyCvQgTWwiFhrYQ2jo_GrzfVBTB6rZ_Q,3493
+mdmint-0.2.0.dist-info/licenses/LICENSE,sha256=12A3kGbtJ5mxsp14iQCCFFbXNAtl4e6DxbW-uy_ovKs,11345
+mdmint-0.2.0.dist-info/licenses/NOTICE,sha256=CFPdjea17oZZigq-DY98BljeDmZxcFZYjrzBTlrSbBY,128
+mdmint-0.2.0.dist-info/METADATA,sha256=jppJnF-XnJqf4qIMW8zxxieA0SJrHxGqsHfLXrrxcbg,8596
+mdmint-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+mdmint-0.2.0.dist-info/entry_points.txt,sha256=5TKP2Caoduad3M9a8LEX-43YuEwQ6yIKRCaixSZ5yQ0,43
+mdmint-0.2.0.dist-info/top_level.txt,sha256=y0zWkYK6Y01xkXT733JQH4LJamjgl8heB_f0FqRXO7Y,7
+mdmint-0.2.0.dist-info/RECORD,,

mdmint-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+