mkdocx 0.1.0

Export MkDocs Material markdown files to clean DOCX documents using pandoc

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 .

With support for post-processing wide tables

uv tool install .[postprocess]

Or 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]

Flag	Description
input	Path to a markdown file or directory
-o, --output	Explicit DOCX output path (single file only, mutually exclusive with -of)
-of, --output-folder	Output folder (default: docx-exports/)
-t, --tag	Filter by frontmatter tag (directory mode only)
--pandoc	Path to pandoc binary (auto-detected if omitted)
--preserve-heading-numbers	Keep leading numbers like "1. Introduction" in headings

Output behaviour

Input	Flags	Output path
File	(none)	docx-exports/<stem>.docx
File	-o path.docx	path.docx
File	-of folder	folder/<stem>.docx
Directory	(none)	docx-exports/ mirroring structure relative to docs/
Directory	-of folder	folder/ mirroring structure relative to docs/
Directory	-t policy	docx-exports/tag/policy/<stem>.docx (flat)
Directory	-t policy -of dir	dir/tag/policy/<stem>.docx (flat)

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