md2word

Convert a Markdown file to a .docx document with a native Word table of contents, embedded filesystem images, and style-based heading auto-numbering.

Requirements

• Python 3.11+
• uv
• pandoc on your PATH

Install

For development (creates a local .venv):

uv sync

To install md2word globally as a command on your PATH (requires Task):

task install        # uv tool install .

Use task install-dev for an editable install (local source changes take effect immediately) and task uninstall to remove it.

Usage

Installed globally:

md2word INPUT.md [-o OUTPUT.docx] [--strip-numbering] [--toc-levels N] [--reference-doc PATH]

Or without installing, from the project directory:

uv run md2word INPUT.md [-o OUTPUT.docx] [--strip-numbering] [--toc-levels N] [--reference-doc PATH]

• Output defaults to INPUT.docx.
• --strip-numbering removes existing 1., 1.2, Chapter N: prefixes from headings so they are not numbered twice.
• --toc-levels sets both the TOC depth and the numbering depth (default 3).
• --reference-doc supplies a pandoc reference docx for base styling (fonts, colors); numbering and TOC auto-update are always applied on top.

How it works

1. Python removes any existing Markdown "Table of Contents" block (a native Word TOC is always generated instead) and optionally strips heading numbers.
2. Pandoc converts the Markdown to .docx, embedding images and inserting a native TOC field. The reader is pandoc markdown with lists_without_preceding_blankline and task_lists enabled, so LLM/CommonMark-style lists that immediately follow a text line (no blank line) render as real lists instead of one run-on paragraph.
3. Python post-processes the .docx to attach a multilevel decimal numbering definition to the Heading styles and to set updateFields, so Word renders 1, 1.1, 1.1.1 and refreshes the TOC when the document is opened.

Numbering comes entirely from Word styles — no numbers are typed into the text.

Development

task test           # or: uv run pytest