Show and Tell: Exporting publication-ready Word (.docx) from Markdown with Quarto (centered math equations, versatile tables & dynamic TOC)

[ls-open]

Hi Quarto community! 👋

When writing papers or reports in Markdown, many of us struggle when the final submission strictly requires Microsoft Word (.docx). Standard docx exports often hit practical styling roadblocks: equation numbers break onto new lines, fonts inherit unwanted Word theme defaults, and multi-section pagination (Roman i, ii front-matter + Arabic 1, 2 body) is tricky to automate.

To solve this, we built and open-sourced md-to-word, an automated publishing pipeline and AI Agent Skill built on top of Quarto.

One thing worth stating up front: this project is Chinese-first. The declarative format's keywords are Chinese (正文：, 页边距：, …), and the built-in CSL styles and the thesis demo target Chinese academic conventions (GB/T 7714, Chinese university thesis templates). An English manuscript does export correctly — the format takes a single Latin font and pt sizes — but you would still be writing Chinese keywords to declare it. The English README covers install and usage.

What it solves:

1. Centered Math with Right-Aligned Numbering: Automatically post-processes numbered math blocks into a 3-column borderless layout where equations stay centered and equation numbers (1) / (1.1) are strictly aligned to the right margin.
2. Versatile & Declarative Tables: Declarative support for academic three-line tables, full gridlines, top/bottom lines, and borderless tables. Table headers automatically repeat on subsequent pages across page breaks.
3. Pure Word 365 Base Template: CJK and Latin fonts are cleanly separated without Word theme inheritance pollution.
4. Independent Section Pagination & Dynamic TOC: Supports native Word dynamic TOC fields ({{< toc >}} with dot leaders) alongside Roman front-matter and Arabic body pagination via custom {{< section >}} markers.
5. Deterministic Quality Gates: Pre-flight syntax validation, post-flight numerical consistency check, and OpenXML style auditing.

It also comes with two out-of-the-box verified demo showcases (an academic thesis and a corporate whitepaper) and bilingual docs.

Repo: https://github.com/ls-open/md-to-word

On the markers: {{< toc >}} and {{< section >}} borrow Quarto's shortcode syntax but are not Quarto shortcodes. They are expanded into raw OpenXML by scripts/expand_markers.py before quarto render runs, so they do nothing under a plain quarto render. Flagging this so nobody copies them into a Quarto-only project expecting them to work.

It is completely free and MIT-licensed. Hope this is helpful to anyone looking to produce publication-grade Word documents from Quarto! Feedback and ideas are warmly welcomed.

[cderv]

Hi, and thanks for sharing this!

I had a look at the repository and the English README, which is clear and helpful. Since this community is English-first, it would be good to link it directly from the post, and modify your links as you changed username in the week end it seems.

One thing that wasn't obvious to me from the post: the tool seems mainly designed for Chinese documents (thesis templates, GB/T 7714 citations, the requirements.txt format spec written with Chinese keywords). I think it would help to say this directly, so people know quickly if it fits their needs.

Also, if I understand correctly, this is not a Quarto extension. It's a separate pipeline that calls quarto render --to docx on a .md file, with a reference doc generated from your spec. Some work is done before the render: the {{< toc >}} and {{< section >}} markers are replaced by raw OpenXML, so they are not real Quarto shortcodes and won't work with a plain quarto render. Some work is done after: the docx is modified for the equation layout and to remove theme fonts.

That said, the problems you describe are real for people who need Word output. If some of them could be improved directly in Quarto (equation numbers on the right, TOC placement, page numbering by section…), we would be happy to hear about it. Feel free to open a feature request with a small example of what you expect, so everyone can benefit from it. Please have a look at our contributing guidelines first: https://github.com/quarto-dev/quarto-cli?tab=contributing-ov-file

Thank you!

[ls-open]

Thanks for reading it closely — and for both catches, which are fixed:

• The links now point at the current username.
• Added a "Chinese-first" note, and put it right after the intro so it's visible before the feature list: an English manuscript does export correctly, you'd just be writing Chinese keywords to declare it.

On the markers: you're right, and it wasn't documented. {{< toc >}} / {{< section >}} borrow the shortcode syntax but are expanded into raw OpenXML by our pre-pass before quarto render runs, so they do nothing standalone. Added an explicit warning.

On contributing upstream: interested. One question first — for "equation number hard right", is that Quarto's to fix, or the pandoc docx writer's? The numbering comes from crossref; the layout looks like it's pandoc's. Point me at the right repo and I'll write it up with a minimal example (and read the contributing guidelines first).

[cderv]

for "equation number hard right", is that Quarto's to fix, or the pandoc docx writer's?
the numbering comes from crossref; the layout looks like it's pandoc's.

It depends if this is a pandoc feature or a quarto feature. If this is related to cross ref, it is probably something from Quarto. If you look into this, and found this is quarto, we welcome a feature request with some details to help us do the right design. This research step is what is important to scope the work correctly.

[ls-open]

Followed your suggestion and looked into it. Short version: the number isn't placed by a layout decision — it is **appended to the equation's math source**, so pandoc renders it as part of the formula. Minimal example: a document whose only content is `$$E = mc^2$$ {#eq-mass}`, rendered with `quarto render --to docx`. In `word/document.xml`, the `<m:oMathPara>` object is the entire paragraph, and the text runs inside it are, in order: `E` `=` `m` `c` `2`, then two em-spaces (`U+2001`), then `(` `1` `)`. Nothing outside the oMath object carries any text. I found where that comes from — `src/resources/filters/crossref/equations.lua`: ```lua local eqNumber = eqQquad -- \qquad(1) if _quarto.format.isHtmlOutput() and (mathMethod == "mathjax" or mathMethod == "katex") then eqNumber = eqTag -- \tag{1} end eq.text = eq.text .. " " .. eqNumber(...) ``` So for docx it is `\qquad(1)` concatenated onto `eq.text` — the math source itself. That explains why a reference-doc template can't fix it (a template cannot reach inside a math object), and it is consistent with the advice you gave in #2618: write a filter. Where it should be fixed I genuinely don't know, and I'd rather ask than guess. The append is presumably the only thing that works across HTML / LaTeX / docx alike, and I suspect the underlying gap is that pandoc's AST has no representation for "centred equation, number hard right" — so there is no docx-writer path either. But Quarto could also emit something docx-specific. You'd know which side of that line this belongs on better than I do. (We work around it downstream by restructuring the equation paragraph into a 1×3 borderless table after render. It works, but it's the kind of thing that would be better solved once, upstream.) Christophe Dervieux ***@***.***> 于2026年10月12日周一 23:56写道：

…

for "equation number hard right", is that Quarto's to fix, or the pandoc docx writer's? the numbering comes from crossref; the layout looks like it's pandoc's. It depends if this is a pandoc feature or a quarto feature. If this is related to cross ref, it is probably something from Quarto. If you look into this, and found this is quarto, we welcome a feature request with some details to help us do the right design. This research step is what is important to scope the work correctly. — Reply to this email directly, view it on GitHub <#15021?email_source=notifications&email_token=BXMIYIR4HT564EE3EGOXVMD5TT5ENA5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCOBYHAYTEMRXUZZGKYLTN5XKMYLVORUG64VFMV3GK3TUVRTG633UMVZF6Y3MNFRWW#discussioncomment-18881227>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BXMIYIWGI557N5EO5SDJYJT5TT5ENAVCNFSNUABIKJSXA33TNF2G64TZHMZDSOBVG44TSMZUHNCGS43DOVZXG2LPNY5TCMBZHEYDANRWUF3AE> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/BXMIYIWGI3MFDA2C44CZMTD5TT5ENA5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCOBYHAYTEMRXUZZGKYLTN5XKMYLVORUG64VFMV3GK3TUVJTG633UMVZF62LPOM> and Android <https://github.com/notifications/mobile/android/BXMIYIRWHFJZDMZLIY5D7PT5TT5ENA5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCOBYHAYTEMRXUZZGKYLTN5XKMYLVORUG64VFMV3GK3TUVZTG633UMVZF6YLOMRZG62LE>. Download it today! You are receiving this because you authored the thread.Message ID: ***@***.*** com>