markdown-docx-compiler

Readable markdown in, polished DOCX out.

markdown-docx-compiler is an AI-native, agent-friendly document compiler that turns readable markdown into polished, editable .docx files optimized for Google Docs import, final human adjustments, and easy PDF export.

Why It Exists

• Readable source for agents and humans - keep documents mostly vanilla markdown instead of burying formatting in HTML or template-only syntax.
• Small sidecars, large rendering gains - move layout and styling into reusable YAML sidecars so the marginal LOC stays low while the rendered result looks much better.
• DOCX as the collaboration surface - compile into polished .docx for final edits in Word or Google Docs instead of treating the output as a dead render.
• PDF-ready last mile - once the DOCX looks right, exporting to PDF with LibreOffice, Word, or your preferred tool is straightforward.
• Agent-friendly CLI - noun-verb commands and --json output fit deep research, canvas-style drafting, and automated reporting workflows.

Ideal Workflow

1. An agent or human drafts a report, memo, proposal, launch brief, or design review in markdown.
2. A sidecar file applies reusable layout and styling without polluting the source markdown.
3. mdc doc create compiles the document into polished, editable DOCX.
4. A human makes the final judgment calls in Word or Google Docs.
5. The finished DOCX can be exported to PDF as the final delivery format.

Samples

Explore complete example document projects in the repository:

• goggle-offer/ - fictionalized offer letter with a logo header, doc header slots, and compensation table. Markdown, Sidecar, PDF preview
• basethree-design-review/ - fictionalized inference company design review with a shaded summary, decision matrix, risk register, and appendix page break. Markdown, Sidecar, PDF preview
• opena1-launch-brief/ - fictionalized bilingual launch brief with centered title styling, editorial callouts, and compact tables. Markdown, Sidecar, PDF preview

Company names in the examples are intentionally fictionalized to avoid trademark issues.

Features

• Plain markdown with optional docx: tags for regions and block anchors
• Sidecar config for layout control (fonts, colors, column widths, per-block styling)
• Composable sidecars via inherits for reusable document defaults
• Deterministic table, footer, and page-level styling
• Google Docs optimized — import fidelity is the primary target
• Agent-friendly CLI with --json output for tool integration
• Document-first workflow for research reports, design docs, launch briefs, internal memos, and final editable handoff

Quick start

pip install markdown-docx-compiler
# or install the CLI with uv / pipx
uv tool install markdown-docx-compiler
pipx install markdown-docx-compiler

Verify the install:

mdc --help

Compile a document:

mdc doc create report.md -o report.docx

With a sidecar config:

mdc doc create report.md --spec report.docx.yaml -o report.docx

If -o is omitted, the compiler writes report.docx next to report.md.

The compiler itself is DOCX-first. PDF export is typically the downstream step once the generated DOCX is approved.

How it works

Write standard markdown with optional YAML front matter for document-level defaults:

---
title: Offer of Employment
font: Arial
text_color: "202124"
---

<!-- docx:doc_header.left -->
![Acme Logo](./logo.png)

<!-- docx:page_footer.center -->
2026-03-19

# Offer of Employment

Dear **Jordan Chen**, ...

## Compensation

<!-- docx:id=comp-table -->
| Component | Details |
| --- | --- |
| Base Salary | $218,000 per year |
| Equity (RSUs) | 1,400 shares over 4 years |

Place a sidecar YAML next to it for styling:

document:
  font: { family: Arial, size: 10.5, color: "202124" }
  page:
    margin: { top: 0.8, bottom: 0.75, left: 1.0, right: 1.0 }

page_footer:
  font: { size: 8, color: "5F6368" }

defaults:
  paragraph:
    spacing: { after: 6, line: 1.15 }

blocks:
  comp-table:
    type: table
    table: { columns: [1fr, 3fr] }

Run mdc doc create offer.md -o offer.docx and you get a fully styled document.

Front matter only controls document-level metadata, font, link, and page settings. Use region tags for header/footer content, and use blocks: anchors for body block overrides, including blocks inside list items.

The important workflow property is that the source markdown stays readable enough for LLMs and humans to keep editing directly, while the sidecar carries the presentational complexity.

CLI reference

mdc doc create report.md -o report.docx     # compile
mdc doc validate report.md                   # dry-run parse
mdc spec show --for report.md --resolved     # inspect merged config
mdc spec create report.docx.yaml             # scaffold a sidecar

Use --json with any command for machine-readable output. Run mdc doc --help or mdc spec --help for detailed reference documentation.

Development

uv sync
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/
uv run mypy src/
uv run pytest tests/
uv build
uvx twine check dist/*

Docs

• Users and agents: mdc doc --help and mdc spec --help
• Maintainers: AGENTS.md
• Release process: RELEASING.md
• Examples: examples/