mkdocx

Export MkDocs Material markdown files to clean DOCX documents using pandoc.

Converts MkDocs markdown files into standard DOCX documents ready to be pasted into a branded template. Heading levels are shifted down by one (Markdown H2 becomes Word Heading 1, etc.) since H1 is the page title handled by MkDocs.

Installation

uv tool install mkdocx

With support for post-processing wide tables

uv tool install mkdocx[postprocess]

Installation From Source

uv tool install .

With support for post-processing wide tables

uv tool install .[postprocess]

Installation for Development

uv pip install -e ".[dev]"

Requirements

• Python 3.10+
• pandoc must be installed and available on PATH (or specify with --pandoc)
• Optional: python-docx for post-processing wide tables (install with pip install mkdocx[postprocess])

Usage

# Single file (output defaults to docx-exports/<filename>.docx)
mkdocx docs/guides/getting-started.md

# Single file with explicit output path
mkdocx docs/guides/getting-started.md -o getting-started.docx

# Single file into a specific output folder
mkdocx docs/guides/getting-started.md -of docx-exports/custom

# Export an entire directory (mirrors structure relative to docs/)
mkdocx docs/guides/

# Export a directory, filtering by frontmatter tag
mkdocx docs/ --tag report

# Export with tag into a custom output folder
mkdocx docs/ -t report -of docx-exports/custom

CLI reference

mkdocx <input> [-o OUTPUT | -of [OUTPUT_FOLDER]] [-t TAG] [--pandoc PATH] [--preserve-heading-numbers]

Output behaviour

Features

• Macro resolution - {{ extra_var }} placeholders from mkdocs.yml are replaced
• Relative link rewriting - .md links become full site URLs
• Admonition conversion - !!! / ??? blocks become styled fenced divs
• Heading shift - H2 becomes H1, H3 becomes H2, etc.
• Empty header table fix - promotes first data row when header is blank
• Abbreviation stripping - removes *[ABBR]: ... definition lines
• Content-aware table widths - Lua filter balances column proportions
• Wide table font shrinking - tables with 4+ columns get a smaller font size

Development

# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest