mdmint 0.2.0__py3-none-any.whl

mdmint/__init__.py

@@ -0,0 +1,18 @@
+"""mdmint — export Markdown files to DOCX and/or PDF.
+
+Pure-Python, cross-platform, minimal dependencies. The two features that cannot
+be rendered statically in pure Python — mermaid diagrams and LaTeX math — use an
+optional renderer if present and fall back gracefully (with a warning) otherwise.
+
+Public API
+----------
+    from mdmint import convert, MarkdownConverter
+
+    convert(["doc.md"], formats=["pdf", "docx"], output="out/")
+    convert_mkdocs("mkdocs.yml", formats=["docx"], template="brand.docx")
+"""
+
+from .core import MarkdownConverter, convert, convert_mkdocs
+
+__version__ = "0.2.0"
+__all__ = ["MarkdownConverter", "convert", "convert_mkdocs", "__version__"]

mdmint/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m mdmint``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mdmint/admonitions.py

@@ -0,0 +1,70 @@
+"""Shared colour table for Markdown admonitions (``!!!`` / ``???`` callouts).
+
+Both writers need to agree on what a "warning" looks like, but they style it
+through completely different mechanisms: :mod:`mdmint.render` emits inline CSS that
+the PDF backend honours, while :mod:`mdmint.backends` paints the DOCX cell with
+low-level OOXML after the fact. Keeping the palette here means the two paths can
+never drift, and adding a type is a one-line change.
+
+Type names follow python-markdown / mkdocs-Material conventions; unknown tags
+degrade to the neutral ``note`` styling rather than raising.
+"""
+
+from __future__ import annotations
+
+# Canonical type -> (accent colour, light background tint), both ``#rrggbb``.
+_CANONICAL: dict[str, tuple[str, str]] = {
+    "note": ("#448aff", "#eaf1ff"),
+    "abstract": ("#00b0ff", "#e5f6ff"),
+    "info": ("#00b8d4", "#e3f8fc"),
+    "tip": ("#00bfa5", "#e3f8f4"),
+    "success": ("#00c853", "#e6f9ec"),
+    "question": ("#64dd17", "#eef9e3"),
+    "warning": ("#ff9100", "#fff3e0"),
+    "failure": ("#ff5252", "#ffecec"),
+    "danger": ("#ff1744", "#ffe9ed"),
+    "bug": ("#f50057", "#ffe6ef"),
+    "example": ("#7c4dff", "#f0ebff"),
+    "quote": ("#9e9e9e", "#f5f5f5"),
+}
+
+# Extra spellings mkdocs/python-markdown accept, mapped to a canonical key.
+_ALIASES: dict[str, str] = {
+    "summary": "abstract",
+    "tldr": "abstract",
+    "hint": "tip",
+    "important": "tip",
+    "check": "success",
+    "done": "success",
+    "help": "question",
+    "faq": "question",
+    "caution": "warning",
+    "attention": "warning",
+    "fail": "failure",
+    "missing": "failure",
+    "error": "danger",
+    "cite": "quote",
+}
+
+DEFAULT = "note"
+
+
+def resolve(tag: str) -> str:
+    """Map any admonition tag (or alias) to a canonical key, defaulting to note."""
+    tag = (tag or "").strip().lower()
+    if tag in _CANONICAL:
+        return tag
+    return _ALIASES.get(tag, DEFAULT)
+
+
+def style_for(tag: str) -> tuple[str, str]:
+    """Return ``(accent, background)`` hex colours for an admonition tag."""
+    return _CANONICAL[resolve(tag)]
+
+
+# Accent colour (upper-case, no ``#``) -> canonical type. The DOCX post-pass uses
+# this to recognise an admonition table by its title colour, which is the only
+# marker that survives htmldocx's class-stripping conversion.
+ACCENTS: dict[str, str] = {
+    accent.lstrip("#").upper(): key for key, (accent, _bg) in _CANONICAL.items()
+}

mdmint/assets.py

@@ -0,0 +1,84 @@
+"""Image asset resolution.
+
+After a Markdown body is rendered to HTML, every ``<img src>`` is rewritten to an
+absolute local filesystem path so that both writers (htmldocx and the PDF backends)
+resolve images identically:
+
+* relative paths   → resolved against the source ``.md`` file's directory
+* ``http(s)`` URLs → downloaded into the work directory (offline-safe thereafter)
+* absolute paths   → kept (these include mermaid/math images we generated)
+* ``data:`` URIs   → left untouched
+
+Anything that cannot be resolved is left as-is with a warning rather than aborting.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import re
+import urllib.request
+from pathlib import Path
+
+log = logging.getLogger("mdmint")
+
+# Matches the src attribute of an <img> tag, capturing the quote and the value.
+_IMG_SRC = re.compile(r'(<img\b[^>]*?\ssrc=)(["\'])(.*?)\2', re.IGNORECASE)
+
+_EXT_BY_TYPE = {
+    "image/png": ".png",
+    "image/jpeg": ".jpg",
+    "image/gif": ".gif",
+    "image/svg+xml": ".svg",
+    "image/webp": ".webp",
+}
+
+
+def _download(url: str, work_dir: Path) -> str | None:
+    digest = hashlib.sha1(url.encode("utf-8"), usedforsecurity=False).hexdigest()[:16]
+    try:
+        req = urllib.request.Request(url, headers={"User-Agent": "mdmint"})  # noqa: S310
+        with urllib.request.urlopen(req, timeout=30) as resp:  # noqa: S310 (user-provided URL)
+            data = resp.read()
+            ctype = resp.headers.get_content_type()
+    except Exception as exc:
+        log.warning("image: could not download %s (%s); leaving as-is.", url, exc)
+        return None
+
+    ext = _EXT_BY_TYPE.get(ctype) or os.path.splitext(url.split("?")[0])[1] or ".img"
+    out_path = work_dir / f"remote-{digest}{ext}"
+    out_path.write_bytes(data)
+    return str(out_path)
+
+
+def _resolve_one(src: str, base_dir: Path, work_dir: Path) -> str:
+    low = src.lower()
+    if low.startswith("data:"):
+        return src
+    if low.startswith(("http://", "https://")):
+        local = _download(src, work_dir)
+        return local if local else src
+    if low.startswith("file://"):
+        return urllib.request.url2pathname(src[7:])
+
+    # Local path: absolute as-is, relative against the markdown file's directory.
+    path = Path(src)
+    if not path.is_absolute():
+        path = base_dir / path
+    abspath = os.path.abspath(path)
+    if not os.path.exists(abspath):
+        log.warning("image: file not found: %s (from src %r)", abspath, src)
+    return abspath
+
+
+def resolve_images(html_body: str, base_dir: Path, work_dir: Path) -> str:
+    """Rewrite every ``<img src>`` in *html_body* to an absolute local path."""
+
+    def repl(m: re.Match[str]) -> str:
+        prefix, quote, src = m.group(1), m.group(2), m.group(3)
+        resolved = _resolve_one(src.strip(), base_dir, work_dir)
+        # Keep the original quote style; the path itself contains no quote chars.
+        return f"{prefix}{quote}{resolved}{quote}"
+
+    return _IMG_SRC.sub(repl, html_body)

mdmint/backends.py

@@ -0,0 +1,244 @@
+"""Output writers: HTML → DOCX and HTML → PDF.
+
+* DOCX uses ``htmldocx`` (built on ``python-docx``) — pure Python, no native deps.
+* PDF uses ``xhtml2pdf`` by default (pure Python) or ``weasyprint`` if explicitly
+  requested (higher fidelity, but needs native Pango/Cairo libraries).
+
+Both PDF backends are imported lazily so a missing optional backend never affects
+the default path.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from importlib.resources import files as _res_files
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from . import admonitions
+
+if TYPE_CHECKING:
+    from docx.document import Document as DocxDocument
+    from docx.oxml.table import CT_TcPr
+
+_IMG_SRC = re.compile(r'(<img\b[^>]*?\ssrc=)(["\'])(.*?)\2', re.IGNORECASE)
+
+
+def load_css() -> str:
+    """Return the bundled default stylesheet."""
+    return _res_files("mdmint.resources").joinpath("default.css").read_text(encoding="utf-8")
+
+
+def wrap_html(body: str, title: str = "", css: str | None = None) -> str:
+    """Wrap an HTML body fragment in a complete, styled HTML document."""
+    if css is None:
+        css = load_css()
+    safe_title = (title or "Document").replace("<", "&lt;").replace(">", "&gt;")
+    return (
+        "<!DOCTYPE html>\n<html><head>"
+        '<meta charset="utf-8" />'
+        f"<title>{safe_title}</title>"
+        f"<style>{css}</style>"
+        f"</head><body>{body}</body></html>"
+    )
+
+
+# --------------------------------------------------------------------------- DOCX
+
+
+def _fit_images_to_page(document: DocxDocument) -> None:
+    """Scale down any inline image larger than the page's text area.
+
+    ``htmldocx`` adds pictures at their native size, and python-docx assumes 72 DPI
+    for images without DPI metadata (mermaid/math PNGs), so wide diagrams overflow
+    the margins. We shrink anything bigger than the printable area to fit, keeping
+    aspect ratio and never upscaling — the DOCX counterpart of CSS ``max-width:100%``.
+    """
+    s = document.sections[0]
+    max_w = (s.page_width or 0) - (s.left_margin or 0) - (s.right_margin or 0)
+    max_h = (s.page_height or 0) - (s.top_margin or 0) - (s.bottom_margin or 0)
+    if max_w <= 0 or max_h <= 0:
+        return
+    for shape in document.inline_shapes:
+        w, h = shape.width, shape.height
+        if not w or not h:
+            continue
+        scale = min(1.0, max_w / w, max_h / h)
+        if scale < 1.0:
+            shape.width = int(w * scale)
+            shape.height = int(h * scale)
+
+
+def _set_cell_shading(tcPr: CT_TcPr, fill: str) -> None:
+    from docx.oxml import OxmlElement
+    from docx.oxml.ns import qn
+
+    shd = OxmlElement("w:shd")
+    shd.set(qn("w:val"), "clear")
+    shd.set(qn("w:color"), "auto")
+    shd.set(qn("w:fill"), fill)
+    tcPr.append(shd)
+
+
+def _set_cell_borders(tcPr: CT_TcPr, accent: str) -> None:
+    """A thick accent rule on the left, hairline grey on the other three sides."""
+    from docx.oxml import OxmlElement
+    from docx.oxml.ns import qn
+
+    borders = OxmlElement("w:tcBorders")
+    edges = {
+        "left": ("24", accent),  # 24 eighths = 3pt accent bar
+        "top": ("4", "DDDDDD"),
+        "bottom": ("4", "DDDDDD"),
+        "right": ("4", "DDDDDD"),
+    }
+    for edge, (size, color) in edges.items():
+        e = OxmlElement(f"w:{edge}")
+        e.set(qn("w:val"), "single")
+        e.set(qn("w:sz"), size)
+        e.set(qn("w:space"), "0")
+        e.set(qn("w:color"), color)
+        borders.append(e)
+    tcPr.append(borders)
+
+
+def _style_admonitions(document: DocxDocument) -> None:
+    """Paint admonition callouts in a freshly built DOCX.
+
+    htmldocx renders our admonitions as bare single-cell tables and discards the
+    CSS that colours them in PDF. We recognise them after the fact — a 1x1 table
+    whose title run carries one of our accent colours (see :mod:`mdmint.admonitions`)
+    — and add the matching cell shading and left accent bar. This is the DOCX twin
+    of the inline CSS emitted by ``render._admonition_open``; anything that is not
+    an admonition (real user tables) is left untouched.
+    """
+    for table in document.tables:
+        if len(table.rows) != 1 or len(table.columns) != 1:
+            continue
+        cell = table.cell(0, 0)
+        title = next((p for p in cell.paragraphs if p.text.strip()), None)
+        run = title and next((r for r in title.runs if r.text.strip()), None)
+        color = run and run.font.color
+        if not color or color.rgb is None:
+            continue
+        accent = str(color.rgb).upper()
+        if accent not in admonitions.ACCENTS:
+            continue
+        _accent, bg = admonitions.style_for(admonitions.ACCENTS[accent])
+        tcPr = cell._tc.get_or_add_tcPr()
+        _set_cell_shading(tcPr, bg.lstrip("#").upper())
+        _set_cell_borders(tcPr, accent)
+
+
+def _flatten_loose_list_items(body: str) -> str:
+    """Unwrap the leading ``<p>`` inside each ``<li>`` for the DOCX path.
+
+    markdown-it wraps list-item content in ``<p>`` whenever the list is *loose*
+    (items separated by blank lines or spanning several lines). htmldocx turns
+    such an ``<li>`` into two paragraphs — an empty ``List Number``/``List Bullet``
+    paragraph carrying the marker, then a separate ``Normal`` paragraph with the
+    text — so the number ends up on its own line. PDF is unaffected (CSS keeps the
+    ``<p>`` inline), so this runs only here. Dropping the leading ``<p>`` wrapper
+    puts the first line back beside its marker; any *further* paragraphs in a
+    multi-block item are left as continuation paragraphs.
+    """
+    from bs4 import BeautifulSoup
+
+    soup = BeautifulSoup(body, "html.parser")
+    for li in soup.find_all("li"):
+        first_p = li.find("p", recursive=False)
+        if first_p is not None:
+            first_p.unwrap()
+    return str(soup)
+
+
+def to_docx(
+    body: str,
+    out_path: str | os.PathLike[str],
+    *,
+    template: str | os.PathLike[str] | None = None,
+    meta: dict[str, str] | None = None,
+    styles: dict[str, str] | None = None,
+) -> None:
+    """Write *body* (an HTML fragment) to a .docx file.
+
+    With a *template* (.docx/.dotx) the template-aware writer in
+    :mod:`mdmint.docxtemplate` is used instead of htmldocx, so the output carries the
+    template's cover, headers/footers and named styles (*meta* fills its
+    ``{{PLACEHOLDERS}}``, *styles* overrides role → style-name choices).
+    """
+    if template is not None:
+        from . import docxtemplate
+
+        docxtemplate.to_docx(body, out_path, template, meta=meta, styles=styles)
+        return
+
+    from docx import Document
+    from htmldocx import HtmlToDocx
+
+    document = Document()
+    parser = HtmlToDocx()
+    parser.add_html_to_document(_flatten_loose_list_items(body), document)
+    _fit_images_to_page(document)
+    _style_admonitions(document)
+    document.save(os.fspath(out_path))
+
+
+# ---------------------------------------------------------------------------- PDF
+
+
+def _xhtml2pdf_link_callback(uri: str, rel: str) -> str:
+    """Resolve resource URIs for xhtml2pdf. Our image srcs are absolute paths."""
+    if uri.startswith("file://"):
+        import urllib.request
+
+        return urllib.request.url2pathname(uri[7:])
+    return uri
+
+
+def _to_file_uris(body: str) -> str:
+    """Convert absolute filesystem image paths to file:// URIs (for weasyprint)."""
+
+    def repl(m: re.Match[str]) -> str:
+        prefix, quote, src = m.group(1), m.group(2), m.group(3)
+        if os.path.isabs(src) and os.path.exists(src):
+            src = Path(src).as_uri()
+        return f"{prefix}{quote}{src}{quote}"
+
+    return _IMG_SRC.sub(repl, body)
+
+
+def to_pdf(
+    body: str,
+    out_path: str | os.PathLike[str],
+    *,
+    backend: str = "xhtml2pdf",
+    title: str = "",
+    work_dir: Path | None = None,
+) -> None:
+    """Write *body* (an HTML fragment) to a .pdf file using the chosen backend."""
+    if backend == "weasyprint":
+        from weasyprint import HTML  # lazy: optional native-dependency backend
+
+        html_doc = wrap_html(_to_file_uris(body), title=title)
+        base = (work_dir or Path.cwd()).as_uri()
+        HTML(string=html_doc, base_url=base).write_pdf(os.fspath(out_path))
+        return
+
+    if backend == "xhtml2pdf":
+        from xhtml2pdf import pisa  # lazy
+
+        html_doc = wrap_html(body, title=title)
+        with open(os.fspath(out_path), "wb") as fh:
+            status = pisa.CreatePDF(
+                src=html_doc,
+                dest=fh,
+                encoding="utf-8",
+                link_callback=_xhtml2pdf_link_callback,
+            )
+        if status.err:
+            raise RuntimeError(f"xhtml2pdf failed to render {out_path}")
+        return
+
+    raise ValueError(f"Unknown PDF backend: {backend!r} (use 'xhtml2pdf' or 'weasyprint')")

mdmint/cli.py

@@ -0,0 +1,164 @@
+"""Command-line interface for mdmint."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from collections.abc import Sequence
+
+from . import __version__
+from .core import VALID_FORMATS, MarkdownConverter
+from .mkdocs import SECTION_STYLES
+
+
+def _parse_formats(value: str) -> list[str]:
+    fmts = [f.strip().lower() for f in value.split(",") if f.strip()]
+    bad = [f for f in fmts if f not in VALID_FORMATS]
+    if bad:
+        raise argparse.ArgumentTypeError(
+            f"invalid format(s): {', '.join(bad)} (choose from {', '.join(VALID_FORMATS)})"
+        )
+    if not fmts:
+        raise argparse.ArgumentTypeError("no formats given")
+    return fmts
+
+
+def _key_value(value: str) -> tuple[str, str]:
+    key, sep, val = value.partition("=")
+    if not sep or not key.strip():
+        raise argparse.ArgumentTypeError(f"expected KEY=VALUE, got {value!r}")
+    return key.strip(), val.strip()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mdmint",
+        description="Export Markdown file(s) to DOCX and/or PDF.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "examples:\n"
+            "  mdmint notes.md                         # -> notes.pdf\n"
+            "  mdmint notes.md -f docx,pdf -o out/     # both formats into out/\n"
+            "  mdmint a.md b.md --merge -o book.pdf    # one merged PDF\n"
+            "  mdmint a.md b.md -f docx                # a.docx and b.docx\n"
+            "  mdmint --mkdocs mkdocs.yml -f docx --template brand.docx -o out/\n"
+            "                                          # one branded DOCX from the nav\n"
+        ),
+    )
+    parser.add_argument("inputs", nargs="*", metavar="INPUT", help="Markdown file(s)")
+    parser.add_argument(
+        "-f",
+        "--format",
+        dest="formats",
+        type=_parse_formats,
+        default=["pdf"],
+        metavar="FMT[,FMT]",
+        help="output format(s): pdf, docx, or both (comma-separated). Default: pdf",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        default=None,
+        help="output directory, or a file path. Default: alongside each input.",
+    )
+    parser.add_argument(
+        "--merge",
+        action="store_true",
+        help="with multiple inputs, produce a single merged file per format",
+    )
+    parser.add_argument(
+        "--toc",
+        action="store_true",
+        help="insert a table of contents (or honour a [TOC] marker)",
+    )
+    parser.add_argument(
+        "--mkdocs",
+        metavar="MKDOCS_YML",
+        default=None,
+        help="build one document from an mkdocs config's nav (instead of INPUTs)",
+    )
+    parser.add_argument(
+        "--section-style",
+        choices=SECTION_STYLES,
+        default=None,
+        help="with --mkdocs: top-level nav sections become part dividers (part, "
+        "default) or every section is a heading above its pages (heading)",
+    )
+    parser.add_argument(
+        "--template",
+        metavar="DOCX",
+        default=None,
+        help="Word template (.docx/.dotx) for DOCX output: its cover, headers, "
+        "footers and styles are used",
+    )
+    parser.add_argument(
+        "--meta",
+        metavar="KEY=VALUE",
+        type=_key_value,
+        action="append",
+        default=[],
+        help="value for a template {{KEY}} placeholder (repeatable); overrides "
+        "front matter / mkdocs.yml",
+    )
+    parser.add_argument(
+        "--style",
+        metavar="ROLE=STYLE",
+        type=_key_value,
+        action="append",
+        default=[],
+        help="use template style STYLE for ROLE, e.g. code='My Code' (repeatable)",
+    )
+    parser.add_argument(
+        "--pdf-backend",
+        choices=("xhtml2pdf", "weasyprint"),
+        default="xhtml2pdf",
+        help="PDF engine. xhtml2pdf (default, pure-Python) or weasyprint (extra).",
+    )
+    parser.add_argument("-v", "--verbose", action="store_true", help="verbose logging")
+    parser.add_argument("--version", action="version", version=f"mdmint {__version__}")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.mkdocs and args.inputs:
+        parser.error("give either INPUT files or --mkdocs, not both")
+    if not args.mkdocs and not args.inputs:
+        parser.error("no INPUT files given (or use --mkdocs MKDOCS_YML)")
+    if args.section_style and not args.mkdocs:
+        parser.error("--section-style only applies with --mkdocs")
+    logging.basicConfig(
+        level=logging.INFO if args.verbose else logging.WARNING,
+        format="%(levelname)s: %(message)s",
+    )
+    try:
+        converter = MarkdownConverter(
+            args.formats,
+            pdf_backend=args.pdf_backend,
+            merge=args.merge,
+            toc=args.toc,
+            template=args.template,
+            meta=dict(args.meta),
+            styles=dict(args.style),
+            section_style=args.section_style,
+        )
+        if args.mkdocs:
+            written = converter.convert_mkdocs(args.mkdocs, output=args.output)
+        else:
+            written = converter.convert(args.inputs, output=args.output)
+    except (ValueError, FileNotFoundError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except ImportError as exc:
+        print(f"error: missing optional dependency — {exc}", file=sys.stderr)
+        return 3
+
+    for path in written:
+        print(path)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())