regen.mde 0.2.2

package/src/build_corpus/docx_exporter.py

@@ -0,0 +1,798 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from html.parser import HTMLParser
+from contextlib import ExitStack
+from dataclasses import dataclass, field
+from importlib.resources import as_file, files
+from pathlib import Path
+from zipfile import ZipFile
+
+from docx import Document
+from docx.enum.style import WD_STYLE_TYPE
+from docx.enum.text import WD_BREAK
+from docx.oxml import OxmlElement
+from docx.oxml.ns import qn
+from docx.shared import Inches, Pt, RGBColor
+from docx.image.exceptions import UnrecognizedImageError
+
+
+INLINE_TOKEN_RE = re.compile(
+    r"(!\[[^\]]*\]\([^)]+\)|\[[^\]]+\]\([^)]+\)|`[^`]+`|\$\$[^$]+\$\$|\$[^$\n]+\$|\*\*\*.+?\*\*\*|\*\*.+?\*\*|\*.+?\*)"
+)
+BARE_URL_RE = re.compile(r"https?://[^\s<>()]+(?:\([^\s<>()]*\)[^\s<>()]*)*")
+LIST_ITEM_RE = re.compile(r"^(\s*)([-*+]|\d+\.)\s+(.*)$")
+TABLE_SEPARATOR_RE = re.compile(r"^\s*\|?(?:\s*:?-{3,}:?\s*\|)+\s*:?-{3,}:?\s*\|?\s*$")
+DEFAULT_TEMPLATE_FILENAME = "md-to-word-template.dotx"
+
+
+@dataclass
+class WordExportStats:
+    paragraphs: int = 0
+    headings: int = 0
+    lists: int = 0
+    tables: int = 0
+    code_blocks: int = 0
+    blockquotes: int = 0
+    images: int = 0
+    equations: int = 0
+    warnings: list[str] = field(default_factory=list)
+
+
+def strip_fence(line: str) -> str:
+    return line.strip()[3:].strip()
+
+
+def split_table_row(line: str) -> list[str]:
+    text = line.strip()
+    if text.startswith("|"):
+        text = text[1:]
+    if text.endswith("|"):
+        text = text[:-1]
+    cells: list[str] = []
+    buffer: list[str] = []
+    escape = False
+    for char in text:
+        if escape:
+            buffer.append(char)
+            escape = False
+            continue
+        if char == "\\":
+            escape = True
+            buffer.append(char)
+            continue
+        if char == "|":
+            cells.append("".join(buffer).strip())
+            buffer.clear()
+            continue
+        buffer.append(char)
+    cells.append("".join(buffer).strip())
+    return cells
+
+
+def markdown_link_parts(token: str) -> tuple[str, str]:
+    match = re.fullmatch(r"!?\[([^\]]*)\]\(([^)]+)\)", token)
+    if not match:
+        return token, ""
+    return match.group(1), match.group(2).strip()
+
+
+def unescape_markdown_text(text: str) -> str:
+    return re.sub(r"\\([\\`*_{}\[\]()#+.!|$-])", r"\1", text)
+
+
+class HTMLTableParser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__()
+        self.rows: list[list[str]] = []
+        self.current_row: list[str] | None = None
+        self.current_cell: list[str] | None = None
+
+    def handle_starttag(self, tag: str, attrs) -> None:  # type: ignore[override]
+        normalized = tag.lower()
+        if normalized == "tr":
+            self.current_row = []
+        elif normalized == "td":
+            self.current_cell = []
+        elif normalized == "br" and self.current_cell is not None:
+            self.current_cell.append("\n")
+
+    def handle_endtag(self, tag: str) -> None:  # type: ignore[override]
+        normalized = tag.lower()
+        if normalized == "td" and self.current_row is not None and self.current_cell is not None:
+            self.current_row.append("".join(self.current_cell).strip())
+            self.current_cell = None
+        elif normalized == "tr" and self.current_row is not None:
+            self.rows.append(self.current_row)
+            self.current_row = None
+
+    def handle_data(self, data: str) -> None:  # type: ignore[override]
+        if self.current_cell is not None:
+            self.current_cell.append(data)
+
+
+def parse_html_table(markup: str) -> list[list[str]]:
+    parser = HTMLTableParser()
+    parser.feed(markup)
+    parser.close()
+    return [row for row in parser.rows if any(cell.strip() for cell in row)]
+
+
+def packaged_template_resource():
+    package_root = f"{__package__}.templates" if __package__ else "build_corpus.templates"
+    return files(package_root).joinpath(DEFAULT_TEMPLATE_FILENAME)
+
+
+def resolve_default_template_path() -> Path | None:
+    try:
+        packaged_template_resource()
+    except ModuleNotFoundError:
+        return None
+    return Path(f"bundled:{DEFAULT_TEMPLATE_FILENAME}")
+
+
+def set_cell_text(cell, text: str) -> None:
+    lines = [segment.strip() for segment in text.replace("<br>", "\n").splitlines()]
+    lines = [line for line in lines if line]
+    if not lines:
+        cell.text = ""
+        return []
+    return lines
+
+
+def append_text_with_breaks(paragraph, text: str) -> None:
+    text = unescape_markdown_text(text)
+    parts = text.split("\n")
+    for index, part in enumerate(parts):
+        if part:
+            paragraph.add_run(part)
+        if index < len(parts) - 1:
+            paragraph.add_run().add_break(WD_BREAK.LINE)
+
+
+def split_trailing_url_punctuation(url: str) -> tuple[str, str]:
+    trailing = []
+    core = url
+    while core and core[-1] in ".,;:!?":
+        trailing.append(core[-1])
+        core = core[:-1]
+    return core, "".join(reversed(trailing))
+
+
+def convert_windows_metafile_to_png(source: Path) -> Path | None:
+    if os.name != "nt":
+        return None
+    target_dir = Path(tempfile.gettempdir()) / "build-corpus-image-fallbacks"
+    target_dir.mkdir(parents=True, exist_ok=True)
+    target = target_dir / f"{source.stem}.png"
+    source_literal = str(source).replace("'", "''")
+    target_literal = str(target).replace("'", "''")
+    command = (
+        "Add-Type -AssemblyName System.Drawing; "
+        f"$img = [System.Drawing.Image]::FromFile('{source_literal}'); "
+        f"$bmp = New-Object System.Drawing.Bitmap $img.Width, $img.Height; "
+        "$gfx = [System.Drawing.Graphics]::FromImage($bmp); "
+        "$gfx.DrawImage($img, 0, 0, $img.Width, $img.Height); "
+        f"$bmp.Save('{target_literal}', [System.Drawing.Imaging.ImageFormat]::Png); "
+        "$gfx.Dispose(); $bmp.Dispose(); $img.Dispose()"
+    )
+    result = subprocess.run(
+        ["powershell", "-NoProfile", "-Command", command],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0 or not target.exists():
+        return None
+    return target
+
+
+def set_paragraph_shading(paragraph, fill: str) -> None:
+    paragraph_pr = paragraph._p.get_or_add_pPr()
+    shading = paragraph_pr.find(qn("w:shd"))
+    if shading is None:
+        shading = OxmlElement("w:shd")
+        paragraph_pr.append(shading)
+    shading.set(qn("w:fill"), fill)
+
+
+def set_paragraph_border(paragraph, color: str) -> None:
+    paragraph_pr = paragraph._p.get_or_add_pPr()
+    borders = paragraph_pr.find(qn("w:pBdr"))
+    if borders is None:
+        borders = OxmlElement("w:pBdr")
+        paragraph_pr.append(borders)
+    left = borders.find(qn("w:left"))
+    if left is None:
+        left = OxmlElement("w:left")
+        borders.append(left)
+    left.set(qn("w:val"), "single")
+    left.set(qn("w:sz"), "10")
+    left.set(qn("w:space"), "12")
+    left.set(qn("w:color"), color)
+
+
+def add_hyperlink(paragraph, text: str, url: str):
+    part = paragraph.part
+    relationship_id = part.relate_to(
+        url,
+        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink",
+        is_external=True,
+    )
+    hyperlink = OxmlElement("w:hyperlink")
+    hyperlink.set(qn("r:id"), relationship_id)
+
+    run = OxmlElement("w:r")
+    rpr = OxmlElement("w:rPr")
+
+    color = OxmlElement("w:color")
+    color.set(qn("w:val"), "2563EB")
+    rpr.append(color)
+
+    underline = OxmlElement("w:u")
+    underline.set(qn("w:val"), "single")
+    rpr.append(underline)
+    run.append(rpr)
+
+    text_node = OxmlElement("w:t")
+    text_node.text = text
+    run.append(text_node)
+    hyperlink.append(run)
+    paragraph._p.append(hyperlink)
+    return hyperlink
+
+
+def append_hyperlink_run(hyperlink, text: str, bold: bool = False, italic: bool = False, code: bool = False) -> None:
+    run = OxmlElement("w:r")
+    rpr = OxmlElement("w:rPr")
+
+    color = OxmlElement("w:color")
+    color.set(qn("w:val"), "2563EB")
+    rpr.append(color)
+
+    underline = OxmlElement("w:u")
+    underline.set(qn("w:val"), "single")
+    rpr.append(underline)
+
+    if bold:
+        rpr.append(OxmlElement("w:b"))
+    if italic:
+        rpr.append(OxmlElement("w:i"))
+
+    fonts_needed = code
+    if fonts_needed:
+        fonts = OxmlElement("w:rFonts")
+        fonts.set(qn("w:ascii"), "Consolas")
+        fonts.set(qn("w:hAnsi"), "Consolas")
+        fonts.set(qn("w:cs"), "Consolas")
+        rpr.append(fonts)
+        size = OxmlElement("w:sz")
+        size.set(qn("w:val"), "20")
+        rpr.append(size)
+
+    run.append(rpr)
+    text_node = OxmlElement("w:t")
+    text_node.text = text
+    run.append(text_node)
+    hyperlink.append(run)
+
+
+def set_picture_metadata(run, source_name: str) -> None:
+    filename = Path(source_name).name
+    try:
+        doc_props = run._r.xpath(".//*[local-name()='docPr']")
+    except Exception:
+        doc_props = []
+    for doc_prop in doc_props:
+        doc_prop.set("name", filename)
+        doc_prop.set("descr", filename)
+        doc_prop.set("title", filename)
+
+
+class MarkdownToDocxExporter:
+    def __init__(
+        self,
+        input_path: Path,
+        output_dir: Path,
+        output_docx: Path | None = None,
+        report_path: Path | None = None,
+        template_path: Path | None = None,
+    ):
+        self.input_path = input_path
+        self.output_dir = output_dir
+        self.output_docx = output_docx or (output_dir / f"{input_path.stem}.docx")
+        self.report_path = report_path or (output_dir / "export-report.json")
+        self._template_resource_stack = ExitStack()
+        self.template_path = self.resolve_template_path(template_path)
+        self.use_template_styles = self.template_path is not None
+        self.stats = WordExportStats()
+
+    def export(self) -> dict:
+        try:
+            self.output_dir.mkdir(parents=True, exist_ok=True)
+            if self.template_path and not self.template_path.exists():
+                raise FileNotFoundError(f"Word template not found: {self.template_path}")
+
+            document = Document()
+            if not self.template_path:
+                self.apply_modern_styles(document)
+            self.ensure_custom_styles(document)
+
+            markdown = self.input_path.read_text(encoding="utf-8")
+            self.render_markdown(document, markdown)
+            document.save(self.output_docx)
+            if self.template_path:
+                self.apply_template_package(self.output_docx, self.template_path)
+
+            report = {
+                "input": str(self.input_path),
+                "output": str(self.output_docx),
+                "template": str(self.template_path) if self.template_path else None,
+                "stats": self.stats.__dict__,
+            }
+            self.report_path.write_text(json.dumps(report, indent=2, ensure_ascii=False), encoding="utf-8")
+            return report
+        finally:
+            self._template_resource_stack.close()
+
+    def resolve_template_path(self, template_path: Path | None) -> Path | None:
+        if template_path is not None:
+            return Path(template_path)
+
+        try:
+            return self._template_resource_stack.enter_context(as_file(packaged_template_resource()))
+        except (FileNotFoundError, ModuleNotFoundError):
+            return None
+
+    def apply_modern_styles(self, document: Document) -> None:
+        section = document.sections[0]
+        section.top_margin = Inches(0.8)
+        section.bottom_margin = Inches(0.8)
+        section.left_margin = Inches(0.9)
+        section.right_margin = Inches(0.9)
+
+        normal = document.styles["Normal"]
+        normal.font.name = "Aptos"
+        normal.font.size = Pt(11)
+        normal.font.color.rgb = RGBColor(31, 41, 55)
+        normal.paragraph_format.space_after = Pt(8)
+        normal.paragraph_format.line_spacing = 1.15
+
+        for level, size in ((1, 22), (2, 17), (3, 14), (4, 12)):
+            style = document.styles[f"Heading {level}"]
+            style.font.name = "Aptos Display"
+            style.font.size = Pt(size)
+            style.font.bold = True
+            style.font.color.rgb = RGBColor(15, 23, 42)
+            style.paragraph_format.space_before = Pt(12 if level == 1 else 10)
+            style.paragraph_format.space_after = Pt(4)
+
+        self.ensure_custom_styles(document)
+
+    def ensure_custom_styles(self, document: Document) -> None:
+        if self.use_template_styles:
+            return
+        if "BuildCorpus Code" not in document.styles:
+            style = document.styles.add_style("BuildCorpus Code", WD_STYLE_TYPE.PARAGRAPH)
+            style.base_style = document.styles["Normal"]
+            style.font.name = "Consolas"
+            style.font.size = Pt(10)
+            style.paragraph_format.left_indent = Inches(0.2)
+            style.paragraph_format.right_indent = Inches(0.2)
+            style.paragraph_format.space_before = Pt(4)
+            style.paragraph_format.space_after = Pt(6)
+
+        if "BuildCorpus Quote" not in document.styles:
+            style = document.styles.add_style("BuildCorpus Quote", WD_STYLE_TYPE.PARAGRAPH)
+            style.base_style = document.styles["Normal"]
+            style.font.italic = True
+            style.font.color.rgb = RGBColor(71, 85, 105)
+            style.paragraph_format.left_indent = Inches(0.35)
+            style.paragraph_format.space_after = Pt(6)
+
+    def render_markdown(self, document: Document, markdown: str) -> None:
+        lines = markdown.splitlines()
+        index = 0
+        while index < len(lines):
+            line = lines[index]
+            stripped = line.strip()
+
+            if not stripped:
+                index += 1
+                continue
+
+            if stripped.startswith("```"):
+                info = strip_fence(line)
+                buffer: list[str] = []
+                index += 1
+                while index < len(lines) and not lines[index].strip().startswith("```"):
+                    buffer.append(lines[index])
+                    index += 1
+                if index < len(lines):
+                    index += 1
+                self.add_code_block(document, "\n".join(buffer), info)
+                continue
+
+            if stripped == "$$":
+                buffer: list[str] = []
+                index += 1
+                while index < len(lines) and lines[index].strip() != "$$":
+                    buffer.append(lines[index])
+                    index += 1
+                if index < len(lines):
+                    index += 1
+                self.add_equation_block(document, "\n".join(buffer).strip())
+                continue
+
+            if stripped.startswith("$$") and stripped.endswith("$$") and len(stripped) > 4:
+                self.add_equation_block(document, stripped[2:-2].strip())
+                index += 1
+                continue
+
+            if stripped.startswith("#"):
+                level = len(stripped) - len(stripped.lstrip("#"))
+                text = stripped[level:].strip()
+                self.add_heading(document, level, text)
+                index += 1
+                continue
+
+            if TABLE_SEPARATOR_RE.match(lines[index + 1]) if index + 1 < len(lines) else False:
+                table_lines = [line, lines[index + 1]]
+                index += 2
+                while index < len(lines) and "|" in lines[index]:
+                    if not lines[index].strip():
+                        break
+                    table_lines.append(lines[index])
+                    index += 1
+                self.add_table(document, table_lines)
+                continue
+
+            if stripped.lower() == "<table>":
+                table_lines = [line]
+                index += 1
+                while index < len(lines):
+                    table_lines.append(lines[index])
+                    if lines[index].strip().lower() == "</table>":
+                        index += 1
+                        break
+                    index += 1
+                self.add_html_table(document, "\n".join(table_lines))
+                continue
+
+            list_match = LIST_ITEM_RE.match(line)
+            if list_match:
+                index = self.add_list(document, lines, index)
+                continue
+
+            if stripped.startswith(">"):
+                quote_lines: list[str] = []
+                while index < len(lines) and lines[index].strip().startswith(">"):
+                    quote_lines.append(lines[index].strip()[1:].strip())
+                    index += 1
+                self.add_blockquote(document, " ".join(quote_lines))
+                continue
+
+            if re.fullmatch(r"[-*_]{3,}", stripped):
+                document.add_paragraph("")
+                index += 1
+                continue
+
+            paragraph_lines = [line.strip()]
+            paragraph_lines = [line.rstrip()]
+            paragraph_breaks = [line.endswith("  ") or line.endswith("\\")]
+            index += 1
+            while index < len(lines):
+                candidate = lines[index]
+                if not candidate.strip():
+                    break
+                if candidate.strip().startswith(("```", "#", ">")):
+                    break
+                if LIST_ITEM_RE.match(candidate):
+                    break
+                if TABLE_SEPARATOR_RE.match(lines[index + 1]) if index + 1 < len(lines) else False:
+                    break
+                paragraph_lines.append(candidate.rstrip())
+                paragraph_breaks.append(candidate.endswith("  ") or candidate.endswith("\\"))
+                index += 1
+            self.add_paragraph(document, self.combine_paragraph_lines(paragraph_lines, paragraph_breaks))
+
+    @staticmethod
+    def combine_paragraph_lines(lines: list[str], breaks: list[bool]) -> str:
+        if not lines:
+            return ""
+        combined = lines[0]
+        for index in range(1, len(lines)):
+            separator = "\n" if breaks[index - 1] else " "
+            combined += separator + lines[index]
+        return combined
+
+    @staticmethod
+    def apply_template_package(output_docx: Path, template_path: Path) -> None:
+        transplant_parts = {
+            "word/styles.xml",
+            "word/stylesWithEffects.xml",
+            "word/numbering.xml",
+            "word/fontTable.xml",
+            "word/settings.xml",
+            "word/webSettings.xml",
+            "word/theme/theme1.xml",
+        }
+        with tempfile.TemporaryDirectory(prefix="build-corpus-template-") as tmp:
+            tmp_dir = Path(tmp)
+            patched = tmp_dir / output_docx.name
+            with ZipFile(output_docx) as out_zip, ZipFile(template_path) as template_zip, ZipFile(patched, "w") as patched_zip:
+                template_names = set(template_zip.namelist())
+                output_names = set(out_zip.namelist())
+                for name in out_zip.namelist():
+                    if name in transplant_parts and name in template_names:
+                        patched_zip.writestr(name, template_zip.read(name))
+                    else:
+                        patched_zip.writestr(name, out_zip.read(name))
+                for name in transplant_parts:
+                    if name in template_names and name not in output_names:
+                        patched_zip.writestr(name, template_zip.read(name))
+            shutil.move(str(patched), output_docx)
+
+    def add_heading(self, document: Document, level: int, text: str) -> None:
+        paragraph = document.add_paragraph(style=f"Heading {min(level, 6)}")
+        self.render_inline(paragraph, text)
+        self.stats.headings += 1
+
+    def add_paragraph(self, document: Document, text: str) -> None:
+        paragraph = document.add_paragraph(style="Normal")
+        self.render_inline(paragraph, text)
+        self.stats.paragraphs += 1
+
+    def add_code_block(self, document: Document, code: str, info: str) -> None:
+        paragraph = document.add_paragraph(style="Normal" if self.use_template_styles else "BuildCorpus Code")
+        if info:
+            label = paragraph.add_run(f"{info}\n")
+            label.bold = True
+            label.font.color.rgb = RGBColor(37, 99, 235)
+        run = paragraph.add_run(code)
+        run.font.name = "Consolas"
+        run.font.size = Pt(10)
+        set_paragraph_shading(paragraph, "F8FAFC")
+        self.stats.code_blocks += 1
+
+    def add_equation_block(self, document: Document, equation: str) -> None:
+        paragraph = document.add_paragraph(style="Normal")
+        paragraph.paragraph_format.left_indent = Inches(0.3)
+        paragraph.paragraph_format.right_indent = Inches(0.3)
+        paragraph.paragraph_format.space_before = Pt(4)
+        paragraph.paragraph_format.space_after = Pt(8)
+        run = paragraph.add_run(equation)
+        run.font.name = "Cambria Math"
+        run.font.size = Pt(11)
+        self.stats.equations += 1
+
+    def add_blockquote(self, document: Document, text: str) -> None:
+        paragraph = document.add_paragraph(style="Quote" if self.use_template_styles else "BuildCorpus Quote")
+        self.render_inline(paragraph, text)
+        set_paragraph_border(paragraph, "CBD5E1")
+        self.stats.blockquotes += 1
+
+    def add_list(self, document: Document, lines: list[str], start: int) -> int:
+        index = start
+        while index < len(lines):
+            match = LIST_ITEM_RE.match(lines[index])
+            if not match:
+                break
+            indent, marker, body = match.groups()
+            ordered = marker.endswith(".")
+            body_lines = [body]
+            lookahead = index + 1
+            while lookahead < len(lines):
+                candidate = lines[lookahead]
+                stripped = candidate.strip()
+                if not stripped:
+                    break
+                if candidate.strip().startswith(("```", "#", ">")):
+                    break
+                if LIST_ITEM_RE.match(candidate):
+                    break
+                if TABLE_SEPARATOR_RE.match(lines[lookahead + 1]) if lookahead + 1 < len(lines) else False:
+                    break
+                if not candidate[:1].isspace():
+                    break
+                body_lines.append(candidate.rstrip())
+                lookahead += 1
+            style_name = self.list_style_name(document, ordered, indent)
+            paragraph = document.add_paragraph(style=style_name)
+            if style_name in {"List Bullet", "List Number"}:
+                paragraph.paragraph_format.left_indent = Inches(0.25 + (len(indent.replace("\t", "  ")) // 2) * 0.18)
+            self.render_inline(paragraph, "\n".join(body_lines))
+            self.stats.lists += 1
+            index = lookahead
+        return index
+
+    def list_style_name(self, document: Document, ordered: bool, indent: str) -> str:
+        level = min(3, max(1, (len(indent.replace("\t", "  ")) // 2) + 1))
+        base = "List Number" if ordered else "List Bullet"
+        candidate = base if level == 1 else f"{base} {level}"
+        return candidate if candidate in document.styles else base
+
+    def add_table(self, document: Document, table_lines: list[str]) -> None:
+        rows = [split_table_row(line) for line in table_lines if not TABLE_SEPARATOR_RE.match(line)]
+        self.add_table_rows(document, rows)
+
+    def add_html_table(self, document: Document, table_markup: str) -> None:
+        self.add_table_rows(document, parse_html_table(table_markup))
+
+    def add_table_rows(self, document: Document, rows: list[list[str]]) -> None:
+        if not rows:
+            return
+        width = max(len(row) for row in rows)
+        table = document.add_table(rows=len(rows), cols=width)
+        table.style = "Light List Accent 1" if "Light List Accent 1" in document.styles else "Table Grid"
+        for row_index, row in enumerate(rows):
+            for col_index in range(width):
+                value = row[col_index] if col_index < len(row) else ""
+                self.render_table_cell(table.cell(row_index, col_index), value)
+        self.stats.tables += 1
+
+    def render_table_cell(self, cell, text: str) -> None:
+        lines = set_cell_text(cell, text)
+        if not lines:
+            cell.text = ""
+            return
+        first = cell.paragraphs[0]
+        first.text = ""
+        self.render_inline(first, lines[0])
+        for line in lines[1:]:
+            paragraph = cell.add_paragraph("")
+            self.render_inline(paragraph, line)
+
+    def render_inline(self, paragraph, text: str) -> None:
+        cursor = 0
+        for match in INLINE_TOKEN_RE.finditer(text):
+            if match.start() > cursor:
+                self.render_plain_text(paragraph, text[cursor:match.start()])
+            token = match.group(0)
+            self.render_inline_token(paragraph, token)
+            cursor = match.end()
+        if cursor < len(text):
+            self.render_plain_text(paragraph, text[cursor:])
+
+    def render_plain_text(self, paragraph, text: str) -> None:
+        cursor = 0
+        for match in BARE_URL_RE.finditer(text):
+            if match.start() > cursor:
+                append_text_with_breaks(paragraph, text[cursor:match.start()])
+            url = match.group(0)
+            normalized_url, trailing = split_trailing_url_punctuation(url)
+            if normalized_url:
+                add_hyperlink(paragraph, normalized_url, normalized_url)
+            if trailing:
+                append_text_with_breaks(paragraph, trailing)
+            cursor = match.end()
+        if cursor < len(text):
+            append_text_with_breaks(paragraph, text[cursor:])
+
+    def render_inline_token(self, paragraph, token: str) -> None:
+        if token.startswith("!["):
+            alt, target = markdown_link_parts(token)
+            image_path = (self.input_path.parent / target).resolve()
+            if target.startswith(("http://", "https://", "data:")):
+                paragraph.add_run(f"[image: {alt or target}]")
+                self.stats.warnings.append(f"Skipped non-local image target: {target}")
+                return
+            if image_path.exists():
+                run = paragraph.add_run()
+                try:
+                    run.add_picture(str(image_path), width=Inches(5.8))
+                    set_picture_metadata(run, target)
+                    self.stats.images += 1
+                except UnrecognizedImageError:
+                    converted = convert_windows_metafile_to_png(image_path)
+                    if converted is not None:
+                        run.add_picture(str(converted), width=Inches(5.8))
+                        set_picture_metadata(run, target)
+                        self.stats.images += 1
+                        self.stats.warnings.append(f"Converted unsupported image to PNG: {target}")
+                    else:
+                        paragraph.add_run(f"[unsupported image: {target}]")
+                        self.stats.warnings.append(f"Unsupported image asset: {target}")
+            else:
+                paragraph.add_run(f"[missing image: {target}]")
+                self.stats.warnings.append(f"Missing image asset: {target}")
+            return
+
+        if token.startswith("["):
+            label, target = markdown_link_parts(token)
+            hyperlink = add_hyperlink(paragraph, "", target)
+            self.render_hyperlink_label(hyperlink, label)
+            return
+
+        if token.startswith("`"):
+            run = paragraph.add_run(token[1:-1])
+            run.font.name = "Consolas"
+            run.font.size = Pt(10)
+            return
+
+        if token.startswith("$$") and token.endswith("$$"):
+            run = paragraph.add_run(token[2:-2])
+            run.font.name = "Cambria Math"
+            run.font.size = Pt(11)
+            self.stats.equations += 1
+            return
+
+        if token.startswith("$") and token.endswith("$"):
+            run = paragraph.add_run(token[1:-1])
+            run.font.name = "Cambria Math"
+            run.font.size = Pt(11)
+            self.stats.equations += 1
+            return
+
+        if token.startswith("***") and token.endswith("***"):
+            run = paragraph.add_run(token[3:-3])
+            run.bold = True
+            run.italic = True
+            return
+
+        if token.startswith("**") and token.endswith("**"):
+            run = paragraph.add_run(token[2:-2])
+            run.bold = True
+            return
+
+        if token.startswith("*") and token.endswith("*"):
+            run = paragraph.add_run(token[1:-1])
+            run.italic = True
+            return
+
+        paragraph.add_run(token)
+
+    def render_hyperlink_label(self, hyperlink, text: str) -> None:
+        cursor = 0
+        for match in INLINE_TOKEN_RE.finditer(text):
+            if match.start() > cursor:
+                append_hyperlink_run(hyperlink, unescape_markdown_text(text[cursor:match.start()]))
+            token = match.group(0)
+            self.render_hyperlink_token(hyperlink, token)
+            cursor = match.end()
+        if cursor < len(text):
+            append_hyperlink_run(hyperlink, unescape_markdown_text(text[cursor:]))
+
+    def render_hyperlink_token(self, hyperlink, token: str) -> None:
+        if token.startswith("`") and token.endswith("`"):
+            append_hyperlink_run(hyperlink, unescape_markdown_text(token[1:-1]), code=True)
+            return
+        if token.startswith("***") and token.endswith("***"):
+            append_hyperlink_run(hyperlink, unescape_markdown_text(token[3:-3]), bold=True, italic=True)
+            return
+        if token.startswith("**") and token.endswith("**"):
+            append_hyperlink_run(hyperlink, unescape_markdown_text(token[2:-2]), bold=True)
+            return
+        if token.startswith("*") and token.endswith("*"):
+            append_hyperlink_run(hyperlink, unescape_markdown_text(token[1:-1]), italic=True)
+            return
+        append_hyperlink_run(hyperlink, unescape_markdown_text(token))
+
+
+def export_markdown_to_docx(
+    input_path: Path,
+    output_root: Path,
+    out_same_dir: bool,
+    template_path: Path | None = None,
+) -> dict:
+    if out_same_dir:
+        output_dir = input_path.parent
+        output_docx = input_path.with_suffix(".docx")
+        report_path = input_path.with_name(f"{input_path.stem}.export-report.json")
+    else:
+        output_dir = output_root / input_path.stem
+        output_docx = None
+        report_path = None
+
+    exporter = MarkdownToDocxExporter(
+        input_path=input_path,
+        output_dir=output_dir,
+        output_docx=output_docx,
+        report_path=report_path,
+        template_path=template_path,
+    )
+    return exporter.export()