DocMarQ

DOCX generation with a fluent API. Core is lean (python-docx plus an SVG rasterizer). Optional [md] extra adds markdown-to-DOCX rendering: documentation with banner headers, letters and contracts in one or two columns, native Word equations, mermaid and more. Sibling library to pdfmarq with the same API shape and .docx output.

Philosophy

DocMarQ wraps python-docx (OOXML zip plumbing, content types, relationships) into a fluent paragraph/run API. You describe document flow; Word handles layout, pagination, and reflow on open.

• Fluent paragraph/run model: doc.para("First.") opens a paragraph, doc.text(" with bold", bold=True) appends a styled run. Close with enter() or let the next block auto-open one.
• One way per feature: doc.table(), doc.image(), doc.bullet(), doc.link(), no overloaded call signatures
• Markdown is optional: core → python-docx + svglib/rlPyCairo/Pillow for SVG, [md] adds markdown-it-py, mdit-py-plugins, PyYAML
• Engine and documents apart: docmarq.md writes markdown content, a document package lays out the page around it
• Banner as contract: in docmarq.paper YAML frontmatter becomes a styled banner with logo, status badge, version, dates
• Letters and contracts: docmarq.legal sets a letter header from frontmatter and signing lines from the style, in one or two columns, or with language versions side by side
• Templates and series: docmarq.merge fills a markdown template with one record, or with each record of a table, a document per record
• Cross-library parity: API shape mirrors pdfmarq, including TableStyle, Styles, parse_color, rgb255, page sizes, and lang_style() for i18n. The same markdown source and style can target both PDF and DOCX.
• Word-native output: opens cleanly in Word, LibreOffice, Google Docs. Templates .dotx / .docx are respected, so themes and styles carry over.

Trade-offs:

• No cursor or coordinate control. Word owns layout. Great for content-driven documents, not for pixel-perfect grids (use pdfmarq if you need that).
• Math becomes a native Word equation, editable and selectable, for the common markdown-math subset. Beyond it the formula is drawn as a picture, and only what neither layer understands is printed as its own LaTeX source, with a warning.
• Syntax highlighting in code blocks is not rendered yet. The language argument is accepted but ignored.
• The dep tree is small but python-docx is the only path to OOXML. If it can't express something (e.g. complex equation OMML), neither can DocMarQ. Drop to doc.doc for raw python-docx access.

Install

pip install docmarq      # core: python-docx
pip install docmarq[md]  # + markdown rendering stack

Examples

from docmarq import DOCX
# Fluent core API
with DOCX("report.docx") as doc:
  doc.font("Calibri", 20, "Bold").para("Quarterly Report")
  doc.font(size=11, mode="Regular")
  doc.para("Revenue up 23% year-over-year.")
  doc.table(
    [["Q1", "120k"], ["Q2", "148k"], ["Q3", "172k"]],
    header=["Quarter", "Revenue"],
    aligns=["C", "R"],
  )
  doc.image("chart.png", width=180, height=80)
  doc.link("google.com", url="https://google.com")

from docmarq.paper import md_to_docx, PaperStyle
# Markdown documentation to DOCX
style = PaperStyle(
  font_body="Calibri",
  font_mono="Consolas",
  page_number_label="Page", # "Page 1/5" in footer
)
md_to_docx(open("doc.md").read(), "doc.docx", style=style)

from docmarq.legal import md_to_docx, md_parallel_to_docx, lang_style
# A contract in two balanced columns, signed by both parties
md_to_docx(open("contract.md").read(), "contract.docx",
  style=lang_style("pl", columns=2, sign="contract"))
# Language versions side by side, each from its own file
md_parallel_to_docx([pl_text, en_text], "contract-pl-en.docx",
  styles=[lang_style("pl"), lang_style("en")])

See example.py for an end-to-end CLI script. It covers a language preset, Word-native fonts, link_root for cross-document references, and base_dir for relative images.

Markdown features

• GitHub-flavored markdown (tables, fenced code, lists, strikethrough)
• YAML frontmatter rendered as a page-1 banner (logo, status badge, version, dates) by docmarq.paper, with signing lines from the style
• Letters, statements and contracts by docmarq.legal: letter header from frontmatter, justified and hyphenated text, two balanced columns, language versions side by side (see legal/guide)
• Mail merge by docmarq.merge: placeholders, conditions, loops and included clauses, every record checked before the first document (see merge/readme)
• Columns in the core API: doc.columns(2), and everything markdown writes flows through them
• Page geometry, fonts, banner toggles and locale come from caller's style=, never from the document (see md/guide)
• Built-in language presets (en|pl|de|fr|es|it|cs|sk) via lang_style(): covers banner labels, callouts, date format, page numbers
• Skip-duplicate-title: drops # X when it matches frontmatter title
• Auto-slugged headings with clickable [text](#anchor) internal links (unicode-aware)
• Local-path links configurable via link_root + link_base
• Math formulas inline $x^2$ and block $$...$$ as native Word equations
• Mermaid diagrams via mermaid-cli (local) or mermaid.ink (network fallback), with a shared cache with pdfmarq
• Footnotes, nested lists, blockquotes, GitHub callouts (> [!NOTE], > [!WARNING], …)
• Images alone in a paragraph become figures sharing text width, wrapping into a grid beyond it
• An image on the same line as text keeps only its alt text, so give a figure its own paragraph

Not supported (use pdfmarq if you need them): syntax highlighting in code blocks, emoji shortcodes, task lists, inline HTML.

Modules

• docmarq: core DOCX API (fluent paragraph/run model, columns)
• docmarq.md: markdown engine (optional [md] extra)
• docmarq.paper: documentation with a frontmatter banner
• docmarq.legal: letters, statements, contracts, parallel versions
• docmarq.merge: mail merge, one record or a document per record of a table

See also

Need PDF instead of .docx? Check PDFMarQ, sibling library with the same API shape and PDF output. It adds syntax highlighting and pre-measured page breaks, and covers a wider slice of LaTeX. Everything else (banner, callouts, mermaid, lang presets, letters and contracts) works the same in both.