Skip to main content

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 --pdf export, 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 (![caption](figure.png)), 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:

  1. 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.
  2. 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 --back document 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

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.

For DOCX the file is read too, but only the parts Word can synthesise: pandoc references its table style (Table) and its character styles (DotGreen, DotRed, …) by name, and a Word gabarit usually does not define them. md2doc injects the <md2doc-table> theme as the Table style (borders + header fill) and each text-family <style:style> as a matching character style, so tables keep their borders and the status dots their colour.

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 and DOCX)
--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 --headless mode. md2doc therefore 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. --pdf is 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 md2doc from 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 passes custom-style values 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. md2doc rewrites 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/.docx to --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.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for markdown2word 0.1.1
File Size Uploaded Provenance Actions
markdown2word-0.1.1.tar.gz 110.3 kB Without provenance Details for markdown2word-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for markdown2word 0.1.1
File Interpreter ABI Platform Actions
markdown2word-0.1.1-py3-none-any.whl Python 3 none any Details for markdown2word-0.1.1-py3-none-any.whl

Total release size: 149.8 kB

Release files / markdown2word-0.1.1.tar.gz

Download URL markdown2word-0.1.1.tar.gz
Size 110.3 kB
Tags Source
SHA-256 checksum
How to use checksums
4d8b68bdfb4897317b32301fc4e124ee0afbd12636f2d8573fcc3d8e0f862fc5
BLAKE2b-256 checksum
How to use checksums
9f9e8da6c89c9fae957ee09643d7c0607c5fa031fb2cd64e1fad1d529d053662
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.1-py3-none-any.whl

Download URL markdown2word-0.1.1-py3-none-any.whl
Size 39.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
da15031c974b2d178d7a2d0115b46901e20475566ac17dda777e7d2ec65c66b7
BLAKE2b-256 checksum
How to use checksums
03bccc380cf5849c3c0bca36e5964d741ac12ba2af1c66ae9a4b9b326b1cb069
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.1

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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page