docmarq 0.2.0

DOCX generation library with fluent API

DocMarQ

DOCX generation with a fluent API. Core is lean (just python-docx). Optional [md] extra adds markdown-to-DOCX rendering with banner headers, mermaid, GitHub callouts 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 → 1 dep (python-docx), [md] adds markdown-it-py, mdit-py-plugins, PyYAML
• Cross-library parity: API shape mirrors pdfmarq, including TableStyle, Styles, parse_color, rgb255, page sizes, and lang_style() for i18n. The same markdown source 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).
• No math support. Word's equation editor is OOXML-native and out of scope. For math-heavy docs use pdfmarq with matplotlib.
• 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.md import md_to_docx, MarkdownStyle
# Markdown to DOCX
style = MarkdownStyle(
  body_family="Calibri",
  mono_family="Consolas",
  line_height=1.4,
)
md_to_docx(open("doc.md").read(), "doc.docx", style=style)

See example.py for an end-to-end CLI script: 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, sign block)
• Nested render: block in frontmatter controls page geometry, fonts, banner toggles, locale (see md-guide)
• Built-in language presets (en|pl|de|fr|es|it|cs|sk) via lang_style(): covers banner labels, callouts, date format
• 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 (or per-doc YAML base:)
• Mermaid diagrams via mermaid-cli (local) or mermaid.ink (network fallback), with a shared cache with pdfmarq
• Footnotes, emoji shortcodes :rocket:, nested lists, blockquotes, GitHub callouts (> [!NOTE], > [!WARNING], …)
• Images with size caps for block and inline use (![alt](logo.svg) works inline at x-height)
• Headerless single-row tables for label/value cards
• Setext-heading-with-image recovery: ![](img.svg)\n--- renders as block image + <hr> instead of a thumbnail-sized setext h2

Not supported (use pdfmarq if you need them): math formulas, syntax highlighting in code blocks, deferred Page N/M totals (Word's page-numbering fields compute live).

Modules

Module	Description	Docs
docmarq	Core DOCX API (fluent paragraph/run model)	docmarq/readme.md
docmarq.md	Markdown-to-DOCX renderer (optional [md] extra)	docmarq/md/readme.md

See also

Need PDF instead of .docx? Check PDFMarQ, the sibling library with the same API shape and PDF output. It adds math formulas, syntax highlighting, and pre-measured page breaks. Otherwise feature parity (banner, callouts, mermaid, lang presets).