md2doc — Markdown + a Word/ODT template → a styled document
md2doc turns a Markdown file with a YAML header into a real .docx or .odt,
built on your own template. It is meant for the common split: you write in plain
text, your colleagues review in Word or LibreOffice.
Report.md + template.docx ──► Report.docx (──► Report.pdf)
Report.md + template.odt ──► Report.odt (──► Report.pdf)
Why
Markdown is quick to write, diffs cleanly and stays readable in a git
repository. Word is what reviewers, managers and clients actually open, comment
on and print. md2doc keeps the source in Markdown while producing a document
that is 100 % native: real styles, real headings, real tables, a real cover page
— not a text dump pasted into a blank file.
The output format is the template's own: give a .docx template and you get a
.docx, give an .odt template and you get an .odt. Use .odt when the
template comes from LibreOffice and must keep features that a
Word round-trip would flatten (frames, columns, a designed table of contents,
an existing back cover).
Requirements
- pandoc 3.x — the conversion engine.
- Python 3.9+ with the packages in
requirements.txt. - LibreOffice (
soffice) — only for the optional--pdfexport, and always for the ODT table-of-contents pass.
Install
pip install markdown2word # installs the `md2doc` command
# or, from a clone:
uv venv .venv && uv pip install --python .venv/bin/python -r requirements.txt
PYTHONPATH=src .venv/bin/python -m md2doc.cli --help
scripts/make_assets.py regenerates the bundled default template
(src/md2doc/assets/template.docx) from pandoc's own reference document. You
only need it if you want to rebuild the stock template.
The Markdown file
The file starts with a YAML front matter between --- lines:
---
title: Rapport d'exemple
tagline: OPEN-PV : outil paramétré
subtitle: PU 10 : comparaison des bases
author:
- Camille Dupont
- Raphaël Jolivet
date: Juillet 2026
year: 2026 # optional; read from `date` otherwise
contract: 2025AC000028
lang: fr-FR
toc: true # insert a table of contents
---
Recognised keys (all become {{ placeholders }} in the template):
| Key | Role |
|---|---|
title |
document title |
tagline |
programme / collection tagline |
subtitle |
document subtitle |
author |
one name or a list; joined with commas |
date |
date (defaults to today) |
year |
year; taken from a 4-digit number found in date otherwise |
contract |
contract number |
lang |
document language (e.g. fr-FR); drives the spell checker |
toc |
true builds the table of contents (same as --toc) |
Any other scalar key is exposed to the template too. The keys above are consumed: they are removed from what is handed to pandoc, so they do not leak into the body.
For ODT, lang sets the language on the default paragraph/character styles and
writes <dc:language> in the document metadata, which is what LibreOffice's
spell checker reads.
The body is ordinary pandoc Markdown: headings, lists (bullet and numbered),
bold, italic, inline code, fenced code blocks, block quotes, tables,
images (), footnotes ([^1]) and links. Each one maps
to a native style, so reviewers can restyle the whole document at once.
The template — what it does
A template is a normal .docx or .odt with two jobs:
- Styles — pandoc uses it as its style reference: paragraph and character styles, page size, margins, headers and footers. The template is meant to be self-sufficient: it should carry every style the body needs, so no separate style file is required.
- Front matter and back matter — for DOCX its body is rendered with
docxtpl from the front matter (cover,
résumé, abstract…). For ODT the body is read as-is and the Markdown body is
spliced where a
{{ body }}marker sits, and an optional--backdocument where{{ back }}sits.
Put any {{ placeholder }} you like in the front matter: {{ title }},
{{ subtitle }}, {{ authors }}, {{ date }}, plus any extra front-matter
key. Two placeholders are special:
| Placeholder | DOCX | ODT |
|---|---|---|
{{ toc }} |
a live Word TOC field | a table of contents rebuilt by md2doc |
{{ pages }} |
a live NUMPAGES field |
a live text:page-count field |
An existing ADEME-styled text:table-of-content element is also filled (its
cached entries are replaced), so an ODT template that already contains a
sommaire keeps its exact look.
Custom styles and table theme
For ODT templates an optional styles file makes everything explicit and keepable
next to the template (pass it with --styles):
<md2doc-styles xmlns:style="…" xmlns:fo="…">
<!-- redirect a pandoc style to one the template already has -->
<md2doc-rename from="Heading_20_1" to="Titre_20_1"/>
<!-- add or override a named style -->
<style:style style:name="Text_20_body" style:family="paragraph"
style:parent-style-name="Normal"/>
<!-- promote a paragraph style to a TOC heading -->
<md2doc-toc-heading style="titre_20_SANS_20_NUMEROTATION" level="1"/>
<!-- borders and header fill for pandoc's automatic table cells -->
<md2doc-table border="#810F3F" header-bg="#810F3F" header-fg="#FFFFFF"/>
</md2doc-styles>
All elements are optional. <md2doc-rename> is preferred over an alias style
when the template's own style drives chapter numbering: an alias with the same
outline level makes LibreOffice drop it.
Customising it
Open the template in Word or LibreOffice and edit it like any document:
- restyle
Normal,Title,Heading 1,Caption, … — the body follows; - change the page size, margins, header and footer;
- edit the front matter, keeping or moving the
{{ ... }}fields.
Save it back and re-run md2doc. Nothing else to configure.
Command-line reference
md2doc INPUT.md [-o OUT] [-t TEMPLATE] [--styles STYLES.xml]
[--back BACK] [--no-cover] [--toc] [--toc-depth N]
[--pdf] [--keep]
| Option | Effect |
|---|---|
-o, --output |
output file (default: next to the input, with the template's extension) |
-t, --template |
template (.docx or .odt; default: bundled template.docx) |
--styles |
explicit custom styles + table theme (ODT) |
--back |
document appended after the body (ODT: spliced at {{ back }}) |
--no-cover |
styles only; keep pandoc's title block (DOCX only) |
--toc |
build a table of contents |
--toc-depth |
heading levels kept in the TOC (default: 3) |
--pdf |
also export a PDF with LibreOffice |
--keep |
keep the intermediate build/ files |
Notes and limits
- ODT table of contents — LibreOffice does not update indexes in
--headlessmode.md2doctherefore fills the entries itself and runs a two-pass build: render once to locate each heading in the PDF, then render again with the page numbers filled in.--pdfis what enables the second pass. - DOCX table of contents — pandoc inserts a real Word TOC field. It is empty until the reader updates it; Word does so on open (pandoc sets the "update fields" flag). In LibreOffice, use Tools ▸ Update ▸ Indexes and tables if the PDF shows it blank.
- Images — relative paths in the Markdown resolve against the working
directory, so run
md2docfrom the project root. Images wider than the template's text area are scaled down to fit, keeping their aspect ratio. - ODF style names — spaces in style names are encoded as
_20_. Pandoc passescustom-stylevalues verbatim, so md2doc encodes them before splicing. - Bullets render blank in LibreOffice / OnlyOffice — pandoc marks its DOCX
bullets with the Word Symbol font (U+F0B7). On a machine without Symbol,
readers show nothing.
md2docrewrites them to a plain•automatically. - Complex fixed pages (multi-column back matter, designed back covers, text
boxes) are not produced by Markdown. Keep such pages in the template, or pass
them as a separate
.odt/.docxto--back.
Layout
md2doc/
pyproject.toml package metadata (distribution: markdown2word)
requirements.txt Python dependencies
scripts/make_assets.py builds the bundled default template
src/md2doc/
cli.py argument parsing, format dispatch, two-pass TOC
frontmatter.py YAML front matter and placeholder context
pandoc.py pandoc / LibreOffice wrappers
docx.py DOCX backend
odt.py ODT backend
assets/template.docx styles + cover (generated; edit freely)
assets/reference.odt pandoc's stock ODT styles, merged on demand
examples/rapport.md sample source
tests/ unit tests
A worked example
The openpv repository shows the ODT path end to end — splitting a delivered
report into a reusable front/back template and rebuilding it from Markdown —
under doc/livrables/pu10/md2doc/.
Metadata
Release files for markdown2word 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| markdown2word-0.1.0.tar.gz | 108.4 kB | Without provenance | Details for markdown2word-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| markdown2word-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for markdown2word-0.1.0-py3-none-any.whl |
Total release size: 146.1 kB
Release files / markdown2word-0.1.0.tar.gz
| Download URL | markdown2word-0.1.0.tar.gz |
|---|---|
| Size | 108.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9d7fb127937ea9a2610737e4210d92cb873eae2f0c840496d79a094cab4b0a8e
|
|
BLAKE2b-256 checksum How to use checksums |
49b343c3298d399908994dee60c52ec764b4bd6791afa043258e8f54dded7dc2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / markdown2word-0.1.0-py3-none-any.whl
| Download URL | markdown2word-0.1.0-py3-none-any.whl |
|---|---|
| Size | 37.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7d76cba63ac0c82b8b7db0c735d5d582b5b2614af65cbeb23cd7f10897b10a84
|
|
BLAKE2b-256 checksum How to use checksums |
4564a6cb0a045baf03553092e16ea122d8f153856d113b8d66004078d5c4a796
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Security for markdown2word 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.