DocMarQ

DOCX generation with a fluent API. Core is lean (python-docx plus an SVG rasterizer). 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 → python-docx + svglib/rlPyCairo/Pillow for SVG, [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).
• 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.md import md_to_docx, MarkdownStyle
# Markdown to DOCX
style = MarkdownStyle(
  font_body="Calibri",
  font_mono="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. 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, sign block)
• 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
• 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 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
• Headerless single-row tables for label/value cards

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

Modules

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. Otherwise feature parity (banner, callouts, mermaid, lang presets).