markdown-docx 0.1.0__py3-none-any.whl

markdown_docx/renderer.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+import os
+import tempfile
+from io import BytesIO
+from pathlib import Path
+from typing import Any
+
+from docx import Document
+from docx.document import Document as DocumentObject
+from docx.enum.section import WD_ORIENT, WD_SECTION
+from docx.enum.table import WD_TABLE_ALIGNMENT
+from docx.enum.text import WD_ALIGN_PARAGRAPH, WD_BREAK
+from docx.shared import Emu
+from docx.text.paragraph import Paragraph
+
+from markdown_docx.errors import MarkdownDocxError, RenderError
+from markdown_docx.images import ImageLoader, rendered_width
+from markdown_docx.models import (
+    CodeBlock,
+    DocumentModel,
+    HeadingBlock,
+    ImageBlock,
+    InlineFragment,
+    ListParagraphBlock,
+    PageBreakBlock,
+    ParagraphBlock,
+    SectionBreakBlock,
+    SectionSettings,
+    TableBlock,
+)
+from markdown_docx.styles import apply_font_overrides, validate_styles
+from markdown_docx.template import load_template
+
+PARAGRAPH_ALIGNMENT = {
+    "left": WD_ALIGN_PARAGRAPH.LEFT,
+    "center": WD_ALIGN_PARAGRAPH.CENTER,
+    "right": WD_ALIGN_PARAGRAPH.RIGHT,
+}
+TABLE_ALIGNMENT = {
+    "left": WD_TABLE_ALIGNMENT.LEFT,
+    "center": WD_TABLE_ALIGNMENT.CENTER,
+    "right": WD_TABLE_ALIGNMENT.RIGHT,
+}
+
+
+def render_docx(
+    model: DocumentModel,
+    output_path: Path,
+    *,
+    template_path: Path | None,
+    base_dir: Path,
+    allow_remote_images: bool,
+) -> dict[str, Any]:
+    document = load_template(template_path)
+    validate_styles(document, model.options)
+    apply_font_overrides(document, model.options)
+    current_settings = model.options.section
+    _apply_section_settings(document.sections[0], current_settings)
+    image_loader = ImageLoader(base_dir, allow_remote=allow_remote_images)
+    reusable = _reusable_initial_paragraph(document)
+    warnings = list(model.warnings)
+    image_seen = False
+
+    try:
+        for block in model.blocks:
+            if isinstance(block, PageBreakBlock):
+                document.add_paragraph().add_run().add_break(WD_BREAK.PAGE)
+            elif isinstance(block, SectionBreakBlock):
+                current_settings = block.settings
+                section = document.add_section(WD_SECTION.NEW_PAGE)
+                _apply_section_settings(section, current_settings)
+            elif isinstance(block, HeadingBlock):
+                paragraph, reusable = _new_paragraph(
+                    document,
+                    style=model.options.styles.headings[block.level],
+                    reusable=reusable,
+                )
+                image_seen |= _render_fragments(
+                    paragraph,
+                    block.fragments,
+                    image_loader=image_loader,
+                    settings=current_settings,
+                    monospace=model.options.fonts.monospace,
+                    line=block.line,
+                    input_path=model.source_name,
+                )
+            elif isinstance(block, ParagraphBlock):
+                style = (
+                    model.options.styles.blockquote if block.role == "blockquote" else model.options.styles.paragraph
+                )
+                paragraph, reusable = _new_paragraph(document, style=style, reusable=reusable)
+                image_seen |= _render_fragments(
+                    paragraph,
+                    block.fragments,
+                    image_loader=image_loader,
+                    settings=current_settings,
+                    monospace=model.options.fonts.monospace,
+                    line=block.line,
+                    input_path=model.source_name,
+                )
+            elif isinstance(block, CodeBlock):
+                paragraph, reusable = _new_paragraph(
+                    document,
+                    style=model.options.styles.code_block,
+                    reusable=reusable,
+                )
+                paragraph.add_run(block.text.rstrip("\n"))
+            elif isinstance(block, ListParagraphBlock):
+                styles = (
+                    model.options.styles.ordered_list
+                    if block.list_kind == "ordered"
+                    else model.options.styles.unordered_list
+                )
+                paragraph, reusable = _new_paragraph(document, style=styles[block.depth], reusable=reusable)
+                image_seen |= _render_fragments(
+                    paragraph,
+                    block.fragments,
+                    image_loader=image_loader,
+                    settings=current_settings,
+                    monospace=model.options.fonts.monospace,
+                    line=block.line,
+                    input_path=model.source_name,
+                )
+            elif isinstance(block, TableBlock):
+                _render_table(
+                    document,
+                    block,
+                    model=model,
+                    settings=current_settings,
+                    image_loader=image_loader,
+                )
+            elif isinstance(block, ImageBlock):
+                paragraph, reusable = _new_paragraph(
+                    document,
+                    style=model.options.styles.paragraph,
+                    reusable=reusable,
+                )
+                paragraph.alignment = PARAGRAPH_ALIGNMENT[block.options.alignment]
+                asset = image_loader.load(block.src, line=block.line, input_path=model.source_name)
+                width = rendered_width(
+                    asset,
+                    block.options,
+                    usable_width=current_settings.usable_width,
+                    line=block.line,
+                    input_path=model.source_name,
+                )
+                paragraph.add_run().add_picture(BytesIO(asset.data), width=Emu(width))
+                image_seen = True
+            else:
+                raise AssertionError(f"Unhandled block type: {type(block).__name__}")
+        if image_seen:
+            warnings.append("image_alt_text_not_embedded")
+        _save_atomically(document, output_path)
+    except MarkdownDocxError:
+        raise
+    except Exception as exc:
+        raise RenderError("render_failed", f"Could not render DOCX: {exc}") from exc
+
+    return {
+        "output": str(output_path),
+        "sections": len(document.sections),
+        "warnings": sorted(set(warnings)),
+    }
+
+
+def _apply_section_settings(section: Any, settings: SectionSettings) -> None:
+    section.orientation = WD_ORIENT.LANDSCAPE if settings.orientation == "landscape" else WD_ORIENT.PORTRAIT
+    section.page_width = Emu(settings.effective_width)
+    section.page_height = Emu(settings.effective_height)
+    section.top_margin = Emu(settings.margins.top)
+    section.right_margin = Emu(settings.margins.right)
+    section.bottom_margin = Emu(settings.margins.bottom)
+    section.left_margin = Emu(settings.margins.left)
+
+
+def _reusable_initial_paragraph(document: DocumentObject) -> Paragraph | None:
+    if len(document.paragraphs) == 1 and not document.tables:
+        paragraph = document.paragraphs[0]
+        if not paragraph.text and not paragraph.runs:
+            return paragraph
+    return None
+
+
+def _new_paragraph(
+    document: DocumentObject,
+    *,
+    style: str,
+    reusable: Paragraph | None,
+) -> tuple[Paragraph, None]:
+    if reusable is not None:
+        reusable.style = style
+        return reusable, None
+    return document.add_paragraph(style=style), None
+
+
+def _render_fragments(
+    paragraph: Paragraph,
+    fragments: list[InlineFragment],
+    *,
+    image_loader: ImageLoader,
+    settings: SectionSettings,
+    monospace: str,
+    line: int,
+    input_path: str,
+) -> bool:
+    image_seen = False
+    for fragment in fragments:
+        if fragment.kind == "break":
+            paragraph.add_run().add_break(WD_BREAK.LINE)
+        elif fragment.kind == "image":
+            asset = image_loader.load(fragment.src or "", line=line, input_path=input_path)
+            width = min(asset.natural_width, settings.usable_width)
+            run = paragraph.add_run()
+            run.bold = fragment.bold or None
+            run.italic = fragment.italic or None
+            run.add_picture(BytesIO(asset.data), width=Emu(width))
+            image_seen = True
+        else:
+            run = paragraph.add_run(fragment.text or "")
+            run.bold = fragment.bold or None
+            run.italic = fragment.italic or None
+            if fragment.code:
+                run.font.name = monospace
+    return image_seen
+
+
+def _render_table(
+    document: DocumentObject,
+    block: TableBlock,
+    *,
+    model: DocumentModel,
+    settings: SectionSettings,
+    image_loader: ImageLoader,
+) -> None:
+    row_data = [block.headers, *block.rows]
+    column_count = len(block.headers)
+    style_name = block.options.style or model.options.styles.table
+    table = document.add_table(rows=len(row_data), cols=column_count, style=style_name)
+    table.alignment = TABLE_ALIGNMENT[block.options.alignment]
+    set_widths = block.options.width == "page" or block.options.column_widths is not None
+    table.autofit = not set_widths
+    widths: list[int] = []
+    if set_widths:
+        ratios = list(block.options.column_widths or (1.0,) * column_count)
+        ratio_total = sum(ratios)
+        widths = [round(settings.usable_width * ratio / ratio_total) for ratio in ratios]
+        widths[-1] += settings.usable_width - sum(widths)
+        for column, width in zip(table.columns, widths, strict=True):
+            column.width = Emu(width)
+
+    for row_index, cells in enumerate(row_data):
+        for column_index, cell_data in enumerate(cells):
+            cell = table.cell(row_index, column_index)
+            if widths:
+                cell.width = Emu(widths[column_index])
+            paragraph = cell.paragraphs[0]
+            paragraph.style = model.options.styles.paragraph
+            paragraph.alignment = PARAGRAPH_ALIGNMENT[cell_data.alignment]
+            _render_fragments(
+                paragraph,
+                cell_data.fragments,
+                image_loader=image_loader,
+                settings=settings,
+                monospace=model.options.fonts.monospace,
+                line=block.line,
+                input_path=model.source_name,
+            )
+
+
+def _save_atomically(document: DocumentObject, output_path: Path) -> None:
+    output_path = output_path.resolve()
+    if not output_path.parent.is_dir():
+        raise RenderError("render_failed", f"Output directory does not exist: {output_path.parent}")
+    descriptor, temporary_name = tempfile.mkstemp(
+        prefix=f".{output_path.stem}-", suffix=".docx", dir=output_path.parent
+    )
+    os.close(descriptor)
+    temporary_path = Path(temporary_name)
+    try:
+        document.save(str(temporary_path))
+        Document(str(temporary_path))
+        temporary_path.replace(output_path)
+    finally:
+        temporary_path.unlink(missing_ok=True)

markdown_docx/skill.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any
+
+from markdown_docx.errors import UsageError
+
+SKILL_NAME = "markdown-docx"
+MANAGED_MARKER = "<!-- managed-by: markdown-docx -->"
+
+SKILL_MD = f"""---
+name: markdown-docx
+description: Create editable Word documents from strict Markdown using `uvx markdown-docx`. Use for authoring, rendering, validating, or inspecting markdown-docx sources and blank DOCX formatting templates.
+---
+
+{MANAGED_MARKER}
+
+# Markdown DOCX
+
+Use the published CLI through `uvx markdown-docx`. It converts strict Markdown into editable Word documents and keeps Word-specific settings inside invisible HTML comments.
+
+Always invoke the tool as `uvx markdown-docx ...`. Do not assume a global install.
+
+## Inspect first
+
+Inspect the syntax and template before authoring a document:
+
+```text
+uvx markdown-docx --syntax
+uvx markdown-docx --inspect-template --template formatting.docx --json
+uvx markdown-docx --list-styles --template formatting.docx
+uvx markdown-docx --list-table-styles --template formatting.docx
+```
+
+Custom templates must be blank `.docx` files. They may contain styles, themes, fonts, numbering definitions, and page defaults. They may not contain body content, tables, drawings, or nonempty headers and footers.
+
+## Render a document
+
+```text
+uvx markdown-docx input.md output.docx --json
+```
+
+If no output is supplied, the tool writes a `.docx` beside the Markdown source. Add `--force` only when replacing generated output is authorized.
+
+## Metadata
+
+Document metadata must be the first non-whitespace content:
+
+```text
+<!-- markdown-docx
+document:
+  page_size: letter
+  orientation: portrait
+  margins:
+    top: 1in
+    right: 1in
+    bottom: 1in
+    left: 1in
+-->
+```
+
+Start a next-page section with a `section` comment. Insert an explicit page break with `<!-- markdown-docx: page-break -->`. Put `table` metadata immediately before a pipe table and `image` metadata immediately before a standalone image.
+
+Run `uvx markdown-docx --syntax` for every accepted key and value.
+
+## Supported Markdown
+
+Use ATX headings, paragraphs, emphasis, strong text, inline code, hard line breaks, fenced code blocks, blockquotes, lists, pipe tables, and local or remote images. Links are rejected in 0.1.0 because `python-docx` 1.2.0 does not provide public hyperlink creation. Raw HTML, task lists, footnotes, horizontal rules, indented code, multi-paragraph list items, and unsupported nested block content are rejected.
+
+Relative image paths resolve from the Markdown file. When reading stdin, provide an output and `--base-dir`. Use `--no-remote-images` for offline or untrusted input.
+
+## Handle results
+
+Prefer `--json` for automation. Success includes the absolute output path, section count, template identifier, and warnings. Failures include a stable code, message, input path, and line when available. Correct the source before retrying.
+"""
+
+
+def default_skills_dir() -> Path:
+    return Path.home() / ".agents" / "skills"
+
+
+def skill_dir(skills_dir: Path | None = None) -> Path:
+    return (skills_dir or default_skills_dir()) / SKILL_NAME
+
+
+def install_skill(skills_dir: Path | None = None) -> dict[str, Any]:
+    target = skill_dir(skills_dir)
+    skill_path = target / "SKILL.md"
+    if target.exists() and not skill_path.exists():
+        raise UsageError(f"Refusing to install into '{target}' because it contains no managed SKILL.md.")
+    if skill_path.exists() and MANAGED_MARKER not in skill_path.read_text(encoding="utf-8"):
+        raise UsageError(f"Refusing to overwrite unmanaged skill file '{skill_path}'.")
+    target.mkdir(parents=True, exist_ok=True)
+    existed = skill_path.exists()
+    previous = skill_path.read_text(encoding="utf-8") if existed else ""
+    updated = existed and previous != SKILL_MD
+    skill_path.write_text(SKILL_MD, encoding="utf-8", newline="\n")
+    return {
+        "installed": True,
+        "created": not existed,
+        "updated": updated,
+        "skill": SKILL_NAME,
+        "path": str(skill_path),
+    }
+
+
+def remove_skill(skills_dir: Path | None = None, *, force: bool = False) -> dict[str, Any]:
+    target = skill_dir(skills_dir)
+    skill_path = target / "SKILL.md"
+    if not target.exists():
+        return {"removed": False, "skill": SKILL_NAME, "path": str(target), "reason": "not_installed"}
+    if not skill_path.exists():
+        raise UsageError(f"Refusing to remove '{target}' because SKILL.md is missing.")
+    content = skill_path.read_text(encoding="utf-8")
+    if MANAGED_MARKER not in content and not force:
+        raise UsageError(f"Refusing to remove unmanaged skill '{target}'. Use --force to override.")
+    extra_paths = [path for path in target.iterdir() if path.name != "SKILL.md"]
+    if extra_paths and not force:
+        names = ", ".join(sorted(path.name for path in extra_paths))
+        raise UsageError(f"Refusing to remove '{target}' because it contains unmanaged entries: {names}. Use --force.")
+    shutil.rmtree(target)
+    return {"removed": True, "skill": SKILL_NAME, "path": str(target)}

markdown_docx/styles.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from docx.document import Document as DocumentObject
+from docx.enum.style import WD_STYLE_TYPE
+
+from markdown_docx.errors import TemplateError
+from markdown_docx.models import DocumentOptions
+
+
+def validate_styles(document: DocumentObject, options: DocumentOptions) -> None:
+    paragraph_names = {
+        options.styles.paragraph,
+        options.styles.blockquote,
+        options.styles.code_block,
+        *options.styles.headings.values(),
+        *options.styles.ordered_list,
+        *options.styles.unordered_list,
+    }
+    for name in sorted(paragraph_names):
+        _require_style(document, name, WD_STYLE_TYPE.PARAGRAPH)
+    _require_style(document, options.styles.table, WD_STYLE_TYPE.TABLE)
+
+
+def apply_font_overrides(document: DocumentObject, options: DocumentOptions) -> None:
+    fonts = options.fonts
+    if fonts.body:
+        body_names = {
+            options.styles.paragraph,
+            options.styles.blockquote,
+            *options.styles.ordered_list,
+            *options.styles.unordered_list,
+        }
+        for name in body_names:
+            document.styles[name].font.name = fonts.body
+    if fonts.headings:
+        for name in options.styles.headings.values():
+            document.styles[name].font.name = fonts.headings
+    document.styles[options.styles.code_block].font.name = fonts.monospace
+
+
+def _require_style(document: DocumentObject, name: str, expected_type: WD_STYLE_TYPE) -> None:
+    try:
+        style = document.styles[name]
+    except KeyError as exc:
+        raise TemplateError("template_style_missing", f"Template is missing required style: {name}") from exc
+    if style.type != expected_type:
+        raise TemplateError(
+            "template_style_type_mismatch",
+            f"Style '{name}' must be a {expected_type.name.lower()} style.",
+        )

markdown_docx/template.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from io import BytesIO
+from pathlib import Path
+from typing import Any, Protocol
+
+from docx import Document
+from docx.document import Document as DocumentObject
+from docx.enum.style import WD_STYLE_TYPE
+from docx.opc.exceptions import PackageNotFoundError
+from docx.text.paragraph import Paragraph
+
+from markdown_docx.assets import default_template_bytes
+from markdown_docx.errors import TemplateError
+
+
+class Story(Protocol):
+    @property
+    def paragraphs(self) -> list[Paragraph]: ...
+
+    @property
+    def tables(self) -> list[Any]: ...
+
+
+def load_template(path: Path | None) -> DocumentObject:
+    if path is None:
+        document = Document(BytesIO(default_template_bytes()))
+        validate_blank_template(document, label="packaged default template")
+        return document
+    resolved = path.resolve()
+    if not resolved.is_file():
+        raise TemplateError("template_not_found", f"Template does not exist: {resolved}")
+    if resolved.suffix.lower() != ".docx":
+        raise TemplateError("unsupported_feature", "Templates must use the .docx format. DOTX is not supported.")
+    try:
+        document = Document(str(resolved))
+    except (PackageNotFoundError, ValueError) as exc:
+        raise TemplateError("template_invalid", f"Template is not a readable DOCX file: {resolved}") from exc
+    validate_blank_template(document, label=str(resolved))
+    return document
+
+
+def validate_blank_template(document: DocumentObject, *, label: str) -> None:
+    errors = blank_template_errors(document)
+    if errors:
+        raise TemplateError(
+            "template_not_blank",
+            f"Template must be blank and formatting-only: {errors[0]}",
+            details={"template": label, "errors": errors},
+        )
+
+
+def blank_template_errors(document: DocumentObject) -> list[str]:
+    errors: list[str] = []
+    if any(paragraph.text.strip() for paragraph in document.paragraphs):
+        errors.append("body contains text")
+    if document.tables:
+        errors.append("body contains tables")
+    if len(document.inline_shapes) or any(_paragraph_has_drawing(p) for p in document.paragraphs):
+        errors.append("body contains images or drawings")
+    for number, section in enumerate(document.sections, start=1):
+        for story_name, story in (("header", section.header), ("footer", section.footer)):
+            if _story_has_content(story):
+                errors.append(f"section {number} {story_name} is not empty")
+    return errors
+
+
+def inspect_template(path: Path | None) -> dict[str, Any]:
+    if path is None:
+        label = "packaged-default"
+        document = Document(BytesIO(default_template_bytes()))
+    else:
+        resolved = path.resolve()
+        label = str(resolved)
+        if not resolved.is_file():
+            raise TemplateError("template_not_found", f"Template does not exist: {resolved}")
+        try:
+            document = Document(str(resolved))
+        except (PackageNotFoundError, ValueError) as exc:
+            raise TemplateError("template_invalid", f"Template is not a readable DOCX file: {resolved}") from exc
+    errors = blank_template_errors(document)
+    groups = {
+        "paragraph": sorted(style.name for style in document.styles if style.type == WD_STYLE_TYPE.PARAGRAPH),
+        "character": sorted(style.name for style in document.styles if style.type == WD_STYLE_TYPE.CHARACTER),
+        "table": sorted(style.name for style in document.styles if style.type == WD_STYLE_TYPE.TABLE),
+    }
+    sections = [
+        {
+            "index": index,
+            "orientation": section.orientation.name.lower() if section.orientation else None,
+            "width_inches": round(section.page_width.inches, 4) if section.page_width else None,
+            "height_inches": round(section.page_height.inches, 4) if section.page_height else None,
+            "margins_inches": {
+                "top": round(section.top_margin.inches, 4) if section.top_margin else None,
+                "right": round(section.right_margin.inches, 4) if section.right_margin else None,
+                "bottom": round(section.bottom_margin.inches, 4) if section.bottom_margin else None,
+                "left": round(section.left_margin.inches, 4) if section.left_margin else None,
+            },
+        }
+        for index, section in enumerate(document.sections, start=1)
+    ]
+    return {
+        "template": label,
+        "valid": not errors,
+        "errors": errors,
+        "styles": groups,
+        "sections": sections,
+    }
+
+
+def _story_has_content(story: Story) -> bool:
+    return bool(story.tables) or any(
+        paragraph.text.strip() or _paragraph_has_drawing(paragraph) for paragraph in story.paragraphs
+    )
+
+
+def _paragraph_has_drawing(paragraph: Paragraph) -> bool:
+    for run in paragraph.runs:
+        if any(not isinstance(item, str) for item in run.iter_inner_content()):
+            return True
+    return False