mkdocx 0.1.3
Export MkDocs Material markdown files to clean DOCX documents using pandoc
Requires Python: >=3.10

# 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

```bash
uv tool install mkdocx
```

With support for post-processing wide tables

```bash
uv tool install mkdocx[postprocess]
```

### Installation From Source

```bash
uv tool install .
```

With support for post-processing wide tables

```bash
uv tool install .[postprocess]
```

### Installation for Development

```bash
uv pip install -e ".[dev]"
```

### Requirements

- Python 3.10+
- [pandoc](https://pandoc.org/) 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

```bash
# 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

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

# Run tests
pytest
```