docstudio 0.2.0__py3-none-any.whl

docstudio/__init__.py

@@ -0,0 +1,35 @@
+"""DocumentStudio — bidirectional document conversion library.
+
+Reverse  (X -> Markdown):  PDF, Word, PPT, Excel, EPUB, HTML, CSV/TSV, JSON,
+                           ZIP, images (OCR / VLM).  Optionally backed by
+                           Microsoft `markitdown` when installed.
+Forward  (Markdown -> X):  HTML, PDF, Word(.docx), LaTeX, EPUB, Excel(.xlsx),
+                           plain text.  High-fidelity export is the part
+                           markitdown does NOT do.
+AI assistant            :  polish, translate, summarise, expand, continue,
+                           grammar, formalise, titles, outline, fix-LaTeX,
+                           free-form instructions.
+Toolbox                 :  table of contents, merge PDFs, extract images.
+Templates               :  academic, techdoc, minutes, readme, weekly, blog.
+
+Quick start
+-----------
+    from docstudio import DocumentStudio
+    ds = DocumentStudio()
+
+    md = ds.to_markdown("report.pdf")                    # anything -> Markdown
+    ds.convert("paper.md", to="pdf", out="paper.pdf")    # Markdown -> anything
+
+    ds.generate_toc(md)                                  # toolbox
+    ds.merge_pdfs(["a.pdf", "b.pdf"], "all.pdf")
+    body = ds.template("academic")                       # template library
+
+    from docstudio.llm import LLM                         # AI assistant
+    ds = DocumentStudio(llm=LLM(base_url="...", api_key="...", model="..."))
+    ds.assist(md, action="polish")
+    ds.assist(md, instruction="把所有表格改成要点列表")
+"""
+from .core import DocumentStudio, ConversionError, registry
+
+__all__ = ["DocumentStudio", "ConversionError", "registry"]
+__version__ = "0.2.0"

docstudio/assistant.py

@@ -0,0 +1,73 @@
+"""AI document assistant — LLM-powered operations on Markdown / plain text.
+
+Mirrors the *AI Assistant* of the Document Studio web app: a fixed set of
+one-shot actions (polish, translate, summarise, expand, ...) plus a free-form
+``instruction``. Every action is a single chat completion against whatever
+OpenAI-compatible endpoint the :class:`~docstudio.llm.LLM` is configured for.
+"""
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+# action key -> system prompt (kept in sync with the web app's AI_ACTS)
+ACTIONS = {
+    "polish":    "你是中文技术写作助手。润色下面的 Markdown：提升流畅度、准确性与可读性，"
+                 "规范标点与格式，严格保留原意与全部信息，不新增不删减。只输出 Markdown，不要解释。",
+    "to_en":     "Translate the following Markdown into fluent, natural English. Preserve all "
+                 "Markdown structure (headings, lists, tables, math $...$, code). Output only the "
+                 "translated Markdown.",
+    "to_zh":     "把下面的 Markdown 翻译成自然流畅的简体中文，保留所有 Markdown 结构"
+                 "（标题、列表、表格、公式 $...$、代码）。只输出翻译后的 Markdown。",
+    "summary":   "为下面的内容写一段简洁、准确的摘要（约150-250字）。只输出摘要的 Markdown 段落，不要解释。",
+    "expand":    "扩展并丰富下面的内容：补充细节、例子与解释，保持原结构与风格，不偏离主题、不编造事实。"
+                 "只输出 Markdown。",
+    "condense":  "精炼下面的内容：去除冗余，保留要点与关键信息，保持 Markdown 结构。只输出 Markdown。",
+    "continue":  "延续下面文档的主题、风格与结构，自然地继续往下写 1-3 段。只输出新增的 Markdown 内容，"
+                 "不要重复已有内容。",
+    "grammar":   "修正下面文档中的语法、拼写与标点错误，不改变原意与写作风格。只输出修正后的 Markdown。",
+    "formal":    "把下面的内容改写为更正式、专业的书面语，保留全部信息与 Markdown 结构。只输出 Markdown。",
+    "titles":    "为下面的文档给出 5 个高质量的标题建议，用 Markdown 无序列表呈现。只输出列表。",
+    "outline":   "根据下面的内容或主题，生成一个结构化的 Markdown 多级标题大纲。只输出大纲。",
+    "fix_latex": "修正下面 LaTeX / Markdown 数学公式中的语法错误（缺失的 $、未配对的花括号、"
+                 "拼错的命令等），不改变实际内容与结构。只输出修正后的内容。",
+}
+
+_CUSTOM_SYS = ("你是专业文档编辑助手。严格按用户指令处理下面的 Markdown 文档/文本。"
+               "只输出处理后的 Markdown 结果，不要解释、不要整篇代码围栏。")
+
+
+def list_actions():
+    """Return the available action keys."""
+    return list(ACTIONS)
+
+
+def _strip_fence(s: str) -> str:
+    s = re.sub(r"^\s*```(?:markdown|md)?\s*\n?", "", s, flags=re.I)
+    s = re.sub(r"\n?```\s*$", "", s)
+    return s.strip()
+
+
+def assist(llm, text: str, action: Optional[str] = None,
+           instruction: Optional[str] = None) -> str:
+    """Run an AI assistant operation on ``text`` and return the result.
+
+    Provide ``action`` (one of :data:`ACTIONS`) and/or a free-form
+    ``instruction``. With both, the instruction refines the chosen action.
+    """
+    if llm is None:
+        raise RuntimeError("assist() needs an LLM — create DocumentStudio(llm=LLM(...)).")
+    text = text or ""
+    if action:
+        if action not in ACTIONS:
+            raise ValueError("unknown action %r; choose from: %s"
+                             % (action, ", ".join(ACTIONS)))
+        system = ACTIONS[action]
+        user = (("指令：%s\n\n" % instruction) if instruction else "") + \
+               (("文档：\n" + text) if text.strip() else "（文档为空）")
+    else:
+        if not instruction:
+            raise ValueError("provide either action= or instruction=")
+        system = _CUSTOM_SYS
+        user = "指令：%s\n\n文档：\n%s" % (instruction, text)
+    return _strip_fence(llm.chat(system, user))

docstudio/cli.py

@@ -0,0 +1,139 @@
+"""Command-line interface.
+
+    docstudio report.pdf                       # -> report.md   (X -> Markdown)
+    docstudio report.pdf -o out.md
+    cat report.pdf | docstudio                 # stdin -> stdout (Markdown)
+    docstudio paper.md --to pdf -o paper.pdf   # Markdown -> anything
+    docstudio scan.pdf --to docx               # PDF -> md -> docx
+    docstudio --list-formats
+
+    docstudio paper.md --toc -o paper.md       # insert a table of contents
+    docstudio notes.md --assist polish -o clean.md           # AI assistant
+    docstudio notes.md --instruction "翻译成英文" -o en.md
+    docstudio --merge a.pdf b.pdf -o all.pdf   # merge PDFs
+    docstudio report.pdf --extract-images ./imgs
+    docstudio --template academic              # print a built-in template
+    docstudio --list-templates
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+import tempfile
+from pathlib import Path
+
+from .core import DocumentStudio, ConversionError
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="docstudio",
+                                description="Bidirectional document conversion (Markdown-centric).")
+    p.add_argument("input", nargs="?", help="input file (omit to read from stdin)")
+    p.add_argument("-o", "--output", help="output file (default: stdout for md, alongside input otherwise)")
+    p.add_argument("--to", help="target format: html, pdf, docx, latex, epub, xlsx, text (default: markdown)")
+    p.add_argument("--no-markitdown", action="store_true", help="never delegate reverse conversion to markitdown")
+    p.add_argument("--vlm-model", help="vision model id for image / scanned-PDF recognition")
+    p.add_argument("--model", help="text model id for the AI assistant (required for --assist)")
+    p.add_argument("--base-url", default="",
+                   help="OpenAI-compatible endpoint, e.g. https://api.openai.com (required for AI ops)")
+    p.add_argument("--api-key", default="")
+    p.add_argument("--list-formats", action="store_true")
+    # toolbox / assistant / templates
+    p.add_argument("--assist", metavar="ACTION",
+                   help="AI action: polish, to_en, to_zh, summary, expand, condense, "
+                        "continue, grammar, formal, titles, outline, fix_latex")
+    p.add_argument("--instruction", help="free-form AI instruction (with or without --assist)")
+    p.add_argument("--toc", action="store_true", help="insert a Markdown table of contents")
+    p.add_argument("--merge", nargs="+", metavar="PDF", help="merge the given PDFs into -o output")
+    p.add_argument("--extract-images", metavar="DIR", help="extract embedded images into DIR")
+    p.add_argument("--template", metavar="NAME", help="print a built-in template and exit")
+    p.add_argument("--list-templates", action="store_true")
+    args = p.parse_args(argv)
+
+    llm = None
+    if args.vlm_model or args.model or args.assist or args.instruction:
+        if (args.assist or args.instruction) and not args.model:
+            p.error("AI operations need --model (e.g. --model gpt-4o-mini)")
+        if not args.base_url:
+            p.error("AI operations need --base-url (your OpenAI-compatible endpoint)")
+        from .llm import LLM
+        llm = LLM(base_url=args.base_url, api_key=args.api_key,
+                  model=args.model or "", vlm_model=args.vlm_model)
+    ds = DocumentStudio(llm=llm, use_markitdown=not args.no_markitdown)
+
+    if args.list_formats:
+        print("inputs :", ", ".join(ds.supported_inputs))
+        print("outputs:", ", ".join(ds.supported_outputs))
+        return 0
+
+    if args.list_templates:
+        for slug, (title, desc) in ds.templates().items():
+            print("%-10s %s — %s" % (slug, title, desc))
+        return 0
+
+    if args.template:
+        sys.stdout.write(ds.template(args.template) + "\n")
+        return 0
+
+    if args.merge:
+        out = args.output or "merged.pdf"
+        ds.merge_pdfs(args.merge, out)
+        print(out, file=sys.stderr)
+        return 0
+
+    # resolve input (file or stdin)
+    if args.input:
+        src = args.input
+    else:
+        data = sys.stdin.buffer.read()
+        tmp = tempfile.NamedTemporaryFile(suffix=".bin", delete=False)
+        tmp.write(data); tmp.close(); src = tmp.name
+
+    try:
+        if args.extract_images:
+            for f in ds.extract_images(src, args.extract_images):
+                print(f)
+            return 0
+
+        # text operations (toc / AI assistant) -> Markdown, optionally then convert
+        if args.toc or args.assist or args.instruction:
+            ext = Path(src).suffix.lower().lstrip(".")
+            md = (Path(src).read_text(encoding="utf-8")
+                  if ext in ("md", "markdown", "txt") else ds.to_markdown(src))
+            if args.toc:
+                md = ds.generate_toc(md)
+            if args.assist or args.instruction:
+                md = ds.assist(md, action=args.assist, instruction=args.instruction)
+            if args.to and args.to != "markdown":
+                tf = tempfile.NamedTemporaryFile(suffix=".md", delete=False,
+                                                 mode="w", encoding="utf-8")
+                tf.write(md); tf.close()
+                out = args.output or "out." + args.to
+                ds.convert(tf.name, to=args.to, out=out)
+                print(out, file=sys.stderr)
+            elif args.output:
+                Path(args.output).write_text(md, encoding="utf-8")
+                print(args.output, file=sys.stderr)
+            else:
+                sys.stdout.write(md + "\n")
+            return 0
+
+        if args.to and args.to != "markdown":
+            out = args.output or str(Path(src).with_suffix("." + args.to))
+            ds.convert(src, to=args.to, out=out)
+            print(out, file=sys.stderr)
+        else:
+            md = ds.to_markdown(src)
+            if args.output:
+                Path(args.output).write_text(md, encoding="utf-8")
+                print(args.output, file=sys.stderr)
+            else:
+                sys.stdout.write(md + "\n")
+    except (ConversionError, ValueError, RuntimeError, KeyError) as e:
+        print("error:", e, file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

docstudio/core.py

@@ -0,0 +1,190 @@
+"""Core orchestration: format detection, the converter registry, and the
+public :class:`DocumentStudio` facade."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional, Union, Callable, Dict
+
+PathLike = Union[str, os.PathLike]
+
+
+class ConversionError(RuntimeError):
+    """Raised when a conversion cannot be completed."""
+
+
+# --------------------------------------------------------------------------- #
+# extension -> logical source format
+# --------------------------------------------------------------------------- #
+EXT_FORMAT: Dict[str, str] = {
+    ".md": "markdown", ".markdown": "markdown", ".txt": "text",
+    ".pdf": "pdf", ".docx": "docx", ".doc": "docx",
+    ".pptx": "pptx", ".ppt": "pptx",
+    ".xlsx": "xlsx", ".xlsm": "xlsx", ".xls": "xlsx",
+    ".epub": "epub", ".zip": "zip",
+    ".csv": "csv", ".tsv": "tsv", ".json": "json",
+    ".html": "html", ".htm": "html", ".tex": "latex",
+    ".png": "image", ".jpg": "image", ".jpeg": "image",
+    ".gif": "image", ".webp": "image", ".bmp": "image",
+}
+
+# logical target format -> default file extension
+TARGET_EXT: Dict[str, str] = {
+    "markdown": ".md", "html": ".html", "pdf": ".pdf", "docx": ".docx",
+    "latex": ".tex", "epub": ".epub", "xlsx": ".xlsx", "text": ".txt",
+}
+
+
+def detect_format(path: PathLike) -> str:
+    ext = Path(path).suffix.lower()
+    if ext not in EXT_FORMAT:
+        raise ConversionError(f"Unsupported input extension: {ext!r}")
+    return EXT_FORMAT[ext]
+
+
+class _Registry:
+    """Holds the ingest (X->md) and export (md->X) callables so the set of
+    supported formats is open for extension, exactly like markitdown plugins."""
+
+    def __init__(self) -> None:
+        self.ingesters: Dict[str, Callable] = {}
+        self.exporters: Dict[str, Callable] = {}
+
+    def ingester(self, *formats: str):
+        def deco(fn):
+            for f in formats:
+                self.ingesters[f] = fn
+            return fn
+        return deco
+
+    def exporter(self, *formats: str):
+        def deco(fn):
+            for f in formats:
+                self.exporters[f] = fn
+            return fn
+        return deco
+
+
+registry = _Registry()
+
+
+class DocumentStudio:
+    """Facade over the converter registry.
+
+    Parameters
+    ----------
+    llm:
+        Optional :class:`docstudio.llm.LLM` used for AI cleanup and, when a
+        vision model is configured, for image / scanned-PDF recognition.
+    use_markitdown:
+        When True (default) and the ``markitdown`` package is installed, it is
+        tried first for the reverse direction; our own converters are the
+        fallback.  Set False to always use the built-in converters.
+    """
+
+    def __init__(self, llm=None, use_markitdown: bool = True) -> None:
+        self.llm = llm
+        self.use_markitdown = use_markitdown
+        # import for side effects: registers the built-in converters
+        from . import ingest, export  # noqa: F401
+
+    # -- reverse: anything -> Markdown ------------------------------------- #
+    def to_markdown(self, source: PathLike, fmt: Optional[str] = None,
+                    **opts) -> str:
+        fmt = fmt or detect_format(source)
+        if fmt == "markdown":
+            return Path(source).read_text(encoding="utf-8")
+
+        if self.use_markitdown and fmt not in ("csv", "tsv", "json"):
+            md = self._try_markitdown(source)
+            if md is not None:
+                return md
+
+        fn = registry.ingesters.get(fmt)
+        if fn is None:
+            raise ConversionError(f"No ingester for format {fmt!r}")
+        return fn(source, ds=self, **opts)
+
+    # -- forward: Markdown -> anything ------------------------------------- #
+    def convert(self, source: PathLike, to: str,
+                out: Optional[PathLike] = None, **opts):
+        """Convert *source* (any supported input) to target format *to*.
+
+        Inputs that are not Markdown are first turned into Markdown, so e.g.
+        ``convert("scan.pdf", to="docx")`` works (PDF -> md -> docx)."""
+        src_fmt = opts.pop("fmt", None) or detect_format(source)
+        markdown_text = (Path(source).read_text(encoding="utf-8")
+                         if src_fmt == "markdown"
+                         else self.to_markdown(source, fmt=src_fmt))
+
+        exporter = registry.exporters.get(to)
+        if exporter is None:
+            raise ConversionError(f"No exporter for target {to!r}")
+
+        if out is None:
+            out = str(Path(source).with_suffix(TARGET_EXT.get(to, "." + to)))
+        result = exporter(markdown_text, out=out, ds=self, **opts)
+        return result if result is not None else out
+
+    # -- helpers ----------------------------------------------------------- #
+    @staticmethod
+    def _try_markitdown(source: PathLike) -> Optional[str]:
+        try:
+            from markitdown import MarkItDown
+        except Exception:
+            return None
+        try:
+            return MarkItDown().convert(str(source)).text_content
+        except Exception:
+            return None
+
+    @property
+    def supported_inputs(self):
+        return sorted(set(registry.ingesters) | {"markdown"})
+
+    @property
+    def supported_outputs(self):
+        return sorted(registry.exporters)
+
+    # -- AI assistant ----------------------------------------------------- #
+    def assist(self, text, action=None, instruction=None):
+        """Run an AI assistant operation (polish / translate / summarise / ...).
+
+        See :data:`docstudio.assistant.ACTIONS` for the action keys, or pass a
+        free-form ``instruction``. Requires ``DocumentStudio(llm=LLM(...))``.
+        """
+        from .assistant import assist
+        return assist(self.llm, text, action=action, instruction=instruction)
+
+    @staticmethod
+    def assist_actions():
+        """List the available AI assistant actions."""
+        from .assistant import list_actions
+        return list_actions()
+
+    # -- toolbox ---------------------------------------------------------- #
+    def generate_toc(self, md, title="目录"):
+        """Insert a Markdown table of contents built from ##/### headings."""
+        from .tools import generate_toc
+        return generate_toc(md, title=title)
+
+    def merge_pdfs(self, paths, out):
+        """Merge several PDFs into one (requires pypdf)."""
+        from .tools import merge_pdfs
+        return merge_pdfs(paths, out)
+
+    def extract_images(self, source, out_dir):
+        """Extract embedded images from PDF/DOCX/PPTX/EPUB into ``out_dir``."""
+        from .tools import extract_images
+        return extract_images(source, out_dir)
+
+    # -- template library ------------------------------------------------- #
+    def template(self, name):
+        """Return the Markdown body of a built-in template."""
+        from .templates import get
+        return get(name)
+
+    def templates(self):
+        """Return ``{slug: (title, description)}`` for built-in templates."""
+        from .templates import info
+        return info()

docstudio/export.py

@@ -0,0 +1,205 @@
+"""Forward exporters: Markdown -> X.
+
+High-fidelity targets (pdf/docx/epub) use a backend strategy: prefer the engine
+that gives the best output and is installed, else raise a clear message telling
+the user which extra to install — the same philosophy markitdown uses for its
+optional dependencies."""
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+from .core import registry, ConversionError
+from .latex import md_to_latex
+
+_CSS = """
+body{font-family:-apple-system,'PingFang SC','Noto Sans SC',sans-serif;
+ font-size:15px;line-height:1.75;color:#1a1d23;max-width:760px;margin:40px auto;padding:0 20px}
+h1,h2,h3{line-height:1.3}
+pre{background:#1f2430;color:#e6e6e6;padding:14px;border-radius:8px;overflow:auto}
+code{font-family:Consolas,monospace}:not(pre)>code{background:#f0f1f4;padding:.12em .4em;border-radius:5px}
+blockquote{border-left:3px solid #e15139;background:#fbeae6;padding:.6em 1em;border-radius:0 7px 7px 0;color:#555}
+table{border-collapse:collapse;width:100%}th,td{border:1px solid #ddd;padding:8px 12px}th{background:#f5f5f5}
+img{max-width:100%}a{color:#2c72d0}
+"""
+
+_KATEX = ('<link rel="stylesheet" '
+          'href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css">'
+          '<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js"></script>'
+          '<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js" '
+          'onload="renderMathInElement(document.body)"></script>')
+
+
+def _md_to_html_fragment(md: str) -> str:
+    import markdown
+    return markdown.markdown(
+        md, extensions=["tables", "fenced_code", "toc", "sane_lists", "footnotes"])
+
+
+def _full_html(md: str, title: str = "", math: bool = True) -> str:
+    body = _md_to_html_fragment(md)
+    head = f"<meta charset='utf-8'><title>{title}</title><style>{_CSS}</style>"
+    if math:
+        head += _KATEX
+    return f"<!DOCTYPE html><html><head>{head}</head><body>{body}</body></html>"
+
+
+@registry.exporter("text")
+def to_text(md, out=None, ds=None, **_):
+    plain = re.sub(r"[#>*_`~]|!\[[^\]]*\]\([^)]*\)", "", md)
+    plain = re.sub(r"\[([^\]]+)\]\([^)]*\)", r"\1", plain)
+    return _write(out, plain.strip(), text=True)
+
+
+@registry.exporter("html")
+def to_html(md, out=None, ds=None, title="", **_):
+    return _write(out, _full_html(md, title), text=True)
+
+
+@registry.exporter("latex")
+def to_latex(md, out=None, ds=None, title="", backend="auto", **_):
+    if backend in ("auto", "pandoc") and shutil.which("pandoc"):
+        return _pandoc(md, out, "latex", extra=["-s"])
+    return _write(out, md_to_latex(md, title=title), text=True)
+
+
+@registry.exporter("xlsx")
+def to_xlsx(md, out=None, ds=None, **_):
+    try:
+        import openpyxl
+    except ImportError as e:
+        raise ConversionError("xlsx export needs `pip install docstudio[office]` (openpyxl)") from e
+    wb = openpyxl.Workbook()
+    wb.remove(wb.active)
+    tables = _extract_tables(md)
+    if not tables:
+        ws = wb.create_sheet("Sheet1")
+        for line in (l for l in md.splitlines() if l.strip()):
+            ws.append([c.strip() for c in re.split(r"\t|\s{2,}|,|，", re.sub(r"[#>*_`]", "", line))])
+    else:
+        seen = set()
+        for k, (name, rows) in enumerate(tables, 1):
+            nm = re.sub(r'[\\/?*\[\]:]', "", name or f"Sheet{k}")[:28] or f"Sheet{k}"
+            base, j = nm, 1
+            while nm in seen:
+                j += 1; nm = base[:26] + "_" + str(j)
+            seen.add(nm)
+            ws = wb.create_sheet(nm)
+            for r in rows:
+                ws.append(r)
+    wb.save(out)
+    return out
+
+
+@registry.exporter("pdf")
+def to_pdf(md, out=None, ds=None, title="", backend="auto", **_):
+    order = (["pandoc", "weasyprint", "playwright"] if backend == "auto" else [backend])
+    errors = []
+    for b in order:
+        try:
+            if b == "pandoc" and shutil.which("pandoc"):
+                return _pandoc(md, out, "pdf", extra=["--pdf-engine=xelatex"])
+            if b == "weasyprint":
+                from weasyprint import HTML  # needs cairo/pango system libs
+                HTML(string=_full_html(md, title, math=False)).write_pdf(out)
+                return out
+            if b == "playwright":
+                return _pdf_playwright(md, out, title)
+        except Exception as e:  # noqa: BLE001
+            errors.append(f"{b}: {e}")
+    raise ConversionError(
+        "No working PDF backend. Install one of:\n"
+        "  • pandoc + a TeX engine (best for math)  -> apt install pandoc texlive-xetex\n"
+        "  • weasyprint                              -> pip install docstudio[pdf-weasy]\n"
+        "  • playwright (headless Chrome, full KaTeX)-> pip install docstudio[pdf-chrome] && playwright install chromium\n"
+        + (" | tried: " + "; ".join(errors) if errors else ""))
+
+
+@registry.exporter("docx")
+def to_docx(md, out=None, ds=None, **_):
+    if shutil.which("pandoc"):
+        return _pandoc(md, out, "docx")
+    try:
+        import docx  # python-docx, basic fallback (no rich tables/math)
+    except ImportError as e:
+        raise ConversionError(
+            "docx export needs pandoc, or `pip install docstudio[office]` for a basic fallback") from e
+    document = docx.Document()
+    for line in md.splitlines():
+        h = re.match(r"^(#{1,6})\s+(.+)", line)
+        if h:
+            document.add_heading(h.group(2), level=min(len(h.group(1)), 4))
+        elif line.strip():
+            document.add_paragraph(re.sub(r"[*`]", "", line))
+    document.save(out)
+    return out
+
+
+@registry.exporter("epub")
+def to_epub(md, out=None, ds=None, title="Document", **_):
+    if shutil.which("pandoc"):
+        return _pandoc(md, out, "epub", extra=["--metadata", f"title={title}"])
+    try:
+        from ebooklib import epub
+    except ImportError as e:
+        raise ConversionError("epub export needs pandoc, or `pip install docstudio[office]` (ebooklib)") from e
+    book = epub.EpubBook()
+    book.set_title(title)
+    ch = epub.EpubHtml(title=title, file_name="ch1.xhtml")
+    ch.content = "<html><body>" + _md_to_html_fragment(md) + "</body></html>"
+    book.add_item(ch)
+    book.spine = ["nav", ch]
+    book.add_item(epub.EpubNcx()); book.add_item(epub.EpubNav())
+    epub.write_epub(out, book)
+    return out
+
+
+# --------------------------------------------------------------------------- #
+# backends / helpers
+# --------------------------------------------------------------------------- #
+def _pandoc(md, out, to, extra=None):
+    cmd = ["pandoc", "-f", "markdown", "-t", to, "-o", str(out)] + (extra or [])
+    subprocess.run(cmd, input=md.encode("utf-8"), check=True)
+    return out
+
+
+def _pdf_playwright(md, out, title):
+    from playwright.sync_api import sync_playwright
+    html = _full_html(md, title, math=True)
+    with sync_playwright() as p:
+        browser = p.chromium.launch()
+        page = browser.new_page()
+        page.set_content(html, wait_until="networkidle")
+        page.pdf(path=str(out), format="A4",
+                 margin={"top": "18mm", "bottom": "18mm", "left": "18mm", "right": "18mm"})
+        browser.close()
+    return out
+
+
+def _extract_tables(md):
+    lines, tables, i, last = md.split("\n"), [], 0, ""
+    while i < len(lines):
+        h = re.match(r"^#{1,6}\s+(.+)", lines[i])
+        if h:
+            last = h.group(1).strip()
+        if (re.match(r"^\s*\|.*\|\s*$", lines[i]) and i + 1 < len(lines)
+                and re.match(r"^\s*\|?[\s:|-]+\|?\s*$", lines[i + 1]) and "-" in lines[i + 1]):
+            block, j = [], i
+            while j < len(lines) and "|" in lines[j]:
+                block.append(lines[j]); j += 1
+            rows = [[c.replace(r"\|", "|").replace("<br>", "\n").strip()
+                     for c in re.sub(r"^\s*\||\|\s*$", "", r).split("|")]
+                    for k, r in enumerate(block) if k != 1]
+            tables.append((last, rows)); last = ""; i = j; continue
+        i += 1
+    return tables
+
+
+def _write(out, data, text=False):
+    if out is None:
+        return data
+    Path(out).write_text(data, encoding="utf-8") if text else Path(out).write_bytes(data)
+    return out