markdown2word 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- markdown2word-0.1.0/.gitignore +7 -0
- markdown2word-0.1.0/.gitlab-ci.yml +18 -0
- markdown2word-0.1.0/CHANGELOG.md +57 -0
- markdown2word-0.1.0/LICENSE +21 -0
- markdown2word-0.1.0/PKG-INFO +246 -0
- markdown2word-0.1.0/README.md +221 -0
- markdown2word-0.1.0/examples/rapport.docx +0 -0
- markdown2word-0.1.0/examples/rapport.md +58 -0
- markdown2word-0.1.0/examples/rapport.pdf +0 -0
- markdown2word-0.1.0/pyproject.toml +44 -0
- markdown2word-0.1.0/requirements.txt +6 -0
- markdown2word-0.1.0/scripts/make_assets.py +151 -0
- markdown2word-0.1.0/src/md2doc/__init__.py +10 -0
- markdown2word-0.1.0/src/md2doc/assets/reference.odt +0 -0
- markdown2word-0.1.0/src/md2doc/assets/template.docx +0 -0
- markdown2word-0.1.0/src/md2doc/cli.py +119 -0
- markdown2word-0.1.0/src/md2doc/docx.py +126 -0
- markdown2word-0.1.0/src/md2doc/frontmatter.py +72 -0
- markdown2word-0.1.0/src/md2doc/odt.py +690 -0
- markdown2word-0.1.0/src/md2doc/pandoc.py +66 -0
- markdown2word-0.1.0/tests/test_frontmatter.py +49 -0
- markdown2word-0.1.0/tests/test_odt.py +132 -0
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# Test pipeline for md2doc. Runs on the Mines Paris GitLab instance.
|
|
2
|
+
#
|
|
3
|
+
# The tests only cover the pure helpers (front matter, ODT/ODF manipulation);
|
|
4
|
+
# a full build additionally needs pandoc and LibreOffice.
|
|
5
|
+
|
|
6
|
+
stages:
|
|
7
|
+
- test
|
|
8
|
+
|
|
9
|
+
unit-tests:
|
|
10
|
+
stage: test
|
|
11
|
+
image: python:3.11-slim
|
|
12
|
+
before_script:
|
|
13
|
+
- pip install --quiet -e ".[dev]"
|
|
14
|
+
script:
|
|
15
|
+
- pytest -q
|
|
16
|
+
rules:
|
|
17
|
+
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
|
|
18
|
+
- if: $CI_COMMIT_BRANCH
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are documented here. The format follows
|
|
4
|
+
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project adheres to
|
|
5
|
+
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
6
|
+
|
|
7
|
+
## [Unreleased]
|
|
8
|
+
|
|
9
|
+
### Added
|
|
10
|
+
- ODT: the front-matter `lang` key now sets the document language on the default
|
|
11
|
+
paragraph/character styles and writes `<dc:language>`, so LibreOffice's spell
|
|
12
|
+
checker uses the right language.
|
|
13
|
+
|
|
14
|
+
### Fixed
|
|
15
|
+
- ODT: the template's own table-of-contents entry styles (e.g. `TM_20_1`) are
|
|
16
|
+
reused, so the sommaire keeps its full-width right tab stop and leader instead
|
|
17
|
+
of a squashed default.
|
|
18
|
+
- ODT: comments in the custom-styles file no longer matched (and dropped) the
|
|
19
|
+
template's unnamed default styles, which silently removed the document
|
|
20
|
+
language.
|
|
21
|
+
|
|
22
|
+
## [0.1.0] — 2026-11-19
|
|
23
|
+
|
|
24
|
+
### Added
|
|
25
|
+
- Package layout (`src/md2doc/`) with a `md2doc` console script; distribution
|
|
26
|
+
name `markdown2word`.
|
|
27
|
+
- **ODT backend**: Markdown + an `.odt` template → `.odt`, natively. The
|
|
28
|
+
template's frames, columns, headers/footers and table of contents survive
|
|
29
|
+
untouched; the Markdown body is spliced at a `{{ body }}` marker and an
|
|
30
|
+
optional back matter at `{{ back }}`.
|
|
31
|
+
- ODT table of contents rebuilt by md2doc with a **two-pass** page-number pass
|
|
32
|
+
(LibreOffice does not update indexes headlessly).
|
|
33
|
+
- Explicit custom styles file (`--styles`) for ODT: named-style injection, style
|
|
34
|
+
renames, TOC-heading promotion, and a table theme for pandoc's automatic cell
|
|
35
|
+
styles.
|
|
36
|
+
- Image frames wider than the template's text area are scaled to fit.
|
|
37
|
+
- ODF style-name normalisation (spaces encoded as `_20_`, as pandoc's
|
|
38
|
+
`custom-style` values are passed verbatim).
|
|
39
|
+
- `{{ pages }}` and `{{ toc }}` placeholders in both backends (live fields in
|
|
40
|
+
DOCX; a `text:page-count` field and a rebuilt TOC in ODT).
|
|
41
|
+
- `scripts/make_assets.py` regenerates the bundled default template.
|
|
42
|
+
|
|
43
|
+
### Changed
|
|
44
|
+
- The template is now self-sufficient: the separate `--reference` style
|
|
45
|
+
document was removed. Custom styling is expressed explicitly next to the ODT
|
|
46
|
+
template.
|
|
47
|
+
- Front-matter `year` is taken from the 4-digit year found in `date`, not from
|
|
48
|
+
the first four characters.
|
|
49
|
+
- `fix_list_bullets()` rewrites pandoc's Symbol-font bullets so they render
|
|
50
|
+
without the Symbol font.
|
|
51
|
+
|
|
52
|
+
### Fixed
|
|
53
|
+
- Body paragraphs map to the template's own body style, keeping its typography.
|
|
54
|
+
- Heading references are redirected to the template's heading style rather than
|
|
55
|
+
aliased, preserving LibreOffice chapter numbering.
|
|
56
|
+
- Distinct auto-style prefixes for body and back matter, avoiding silent style
|
|
57
|
+
collisions.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Raphaël Jolivet
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,246 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: markdown2word
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Markdown + YAML front matter + a Word/ODT template -> styled document
|
|
5
|
+
Project-URL: Source, https://git.sophia.minesparis.psl.eu/rjolivet/md2doc
|
|
6
|
+
Author: Raphaël Jolivet
|
|
7
|
+
License: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Keywords: docx,markdown,odt,opendocument,pandoc,template
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Topic :: Text Processing :: Markup
|
|
16
|
+
Requires-Python: >=3.9
|
|
17
|
+
Requires-Dist: docxcompose>=1.4
|
|
18
|
+
Requires-Dist: docxtpl>=0.18
|
|
19
|
+
Requires-Dist: lxml>=4.9
|
|
20
|
+
Requires-Dist: python-docx>=1.1
|
|
21
|
+
Requires-Dist: pyyaml>=6.0
|
|
22
|
+
Provides-Extra: dev
|
|
23
|
+
Requires-Dist: pytest>=7.0; extra == 'dev'
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
|
|
26
|
+
# md2doc — Markdown + a Word/ODT template → a styled document
|
|
27
|
+
|
|
28
|
+
`md2doc` turns a Markdown file with a YAML header into a real `.docx` or `.odt`,
|
|
29
|
+
built on your own template. It is meant for the common split: you write in plain
|
|
30
|
+
text, your colleagues review in Word or LibreOffice.
|
|
31
|
+
|
|
32
|
+
```
|
|
33
|
+
Report.md + template.docx ──► Report.docx (──► Report.pdf)
|
|
34
|
+
Report.md + template.odt ──► Report.odt (──► Report.pdf)
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Why
|
|
38
|
+
|
|
39
|
+
Markdown is quick to write, diffs cleanly and stays readable in a git
|
|
40
|
+
repository. Word is what reviewers, managers and clients actually open, comment
|
|
41
|
+
on and print. `md2doc` keeps the source in Markdown while producing a document
|
|
42
|
+
that is 100 % native: real styles, real headings, real tables, a real cover page
|
|
43
|
+
— not a text dump pasted into a blank file.
|
|
44
|
+
|
|
45
|
+
The output format is the template's own: give a `.docx` template and you get a
|
|
46
|
+
`.docx`, give an `.odt` template and you get an `.odt`. Use `.odt` when the
|
|
47
|
+
template comes from LibreOffice and must keep features that a
|
|
48
|
+
Word round-trip would flatten (frames, columns, a designed table of contents,
|
|
49
|
+
an existing back cover).
|
|
50
|
+
|
|
51
|
+
## Requirements
|
|
52
|
+
|
|
53
|
+
- [pandoc](https://pandoc.org) 3.x — the conversion engine.
|
|
54
|
+
- Python 3.9+ with the packages in `requirements.txt`.
|
|
55
|
+
- LibreOffice (`soffice`) — only for the optional `--pdf` export, and always for
|
|
56
|
+
the ODT table-of-contents pass.
|
|
57
|
+
|
|
58
|
+
## Install
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
pip install markdown2word # installs the `md2doc` command
|
|
62
|
+
# or, from a clone:
|
|
63
|
+
uv venv .venv && uv pip install --python .venv/bin/python -r requirements.txt
|
|
64
|
+
PYTHONPATH=src .venv/bin/python -m md2doc.cli --help
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
`scripts/make_assets.py` regenerates the bundled default template
|
|
68
|
+
(`src/md2doc/assets/template.docx`) from pandoc's own reference document. You
|
|
69
|
+
only need it if you want to rebuild the stock template.
|
|
70
|
+
|
|
71
|
+
## The Markdown file
|
|
72
|
+
|
|
73
|
+
The file starts with a YAML front matter between `---` lines:
|
|
74
|
+
|
|
75
|
+
```yaml
|
|
76
|
+
---
|
|
77
|
+
title: Rapport d'exemple
|
|
78
|
+
tagline: OPEN-PV : outil paramétré
|
|
79
|
+
subtitle: PU 10 : comparaison des bases
|
|
80
|
+
author:
|
|
81
|
+
- Camille Dupont
|
|
82
|
+
- Raphaël Jolivet
|
|
83
|
+
date: Juillet 2026
|
|
84
|
+
year: 2026 # optional; read from `date` otherwise
|
|
85
|
+
contract: 2025AC000028
|
|
86
|
+
lang: fr-FR
|
|
87
|
+
toc: true # insert a table of contents
|
|
88
|
+
---
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Recognised keys (all become `{{ placeholders }}` in the template):
|
|
92
|
+
|
|
93
|
+
| Key | Role |
|
|
94
|
+
|------------|-------------------------------------------------------------------|
|
|
95
|
+
| `title` | document title |
|
|
96
|
+
| `tagline` | programme / collection tagline |
|
|
97
|
+
| `subtitle` | document subtitle |
|
|
98
|
+
| `author` | one name or a list; joined with commas |
|
|
99
|
+
| `date` | date (defaults to today) |
|
|
100
|
+
| `year` | year; taken from a 4-digit number found in `date` otherwise |
|
|
101
|
+
| `contract` | contract number |
|
|
102
|
+
| `lang` | document language (e.g. `fr-FR`); drives the spell checker |
|
|
103
|
+
| `toc` | `true` builds the table of contents (same as `--toc`) |
|
|
104
|
+
|
|
105
|
+
Any other scalar key is exposed to the template too. The keys above are
|
|
106
|
+
*consumed*: they are removed from what is handed to pandoc, so they do not leak
|
|
107
|
+
into the body.
|
|
108
|
+
|
|
109
|
+
For ODT, `lang` sets the language on the default paragraph/character styles and
|
|
110
|
+
writes `<dc:language>` in the document metadata, which is what LibreOffice's
|
|
111
|
+
spell checker reads.
|
|
112
|
+
|
|
113
|
+
The body is ordinary pandoc Markdown: headings, lists (bullet and numbered),
|
|
114
|
+
**bold**, *italic*, `inline code`, fenced code blocks, block quotes, tables,
|
|
115
|
+
images (``), footnotes (`[^1]`) and links. Each one maps
|
|
116
|
+
to a native style, so reviewers can restyle the whole document at once.
|
|
117
|
+
|
|
118
|
+
## The template — what it does
|
|
119
|
+
|
|
120
|
+
A template is a normal `.docx` or `.odt` with two jobs:
|
|
121
|
+
|
|
122
|
+
1. **Styles** — pandoc uses it as its style reference: paragraph and character
|
|
123
|
+
styles, page size, margins, headers and footers. The template is meant to be
|
|
124
|
+
**self-sufficient**: it should carry every style the body needs, so no
|
|
125
|
+
separate style file is required.
|
|
126
|
+
2. **Front matter and back matter** — for DOCX its body is rendered with
|
|
127
|
+
[docxtpl](https://docxtpl.readthedocs.io) from the front matter (cover,
|
|
128
|
+
résumé, abstract…). For ODT the body is read as-is and the Markdown body is
|
|
129
|
+
spliced where a `{{ body }}` marker sits, and an optional `--back` document
|
|
130
|
+
where `{{ back }}` sits.
|
|
131
|
+
|
|
132
|
+
Put any `{{ placeholder }}` you like in the front matter: `{{ title }}`,
|
|
133
|
+
`{{ subtitle }}`, `{{ authors }}`, `{{ date }}`, plus any extra front-matter
|
|
134
|
+
key. Two placeholders are special:
|
|
135
|
+
|
|
136
|
+
| Placeholder | DOCX | ODT |
|
|
137
|
+
|-------------|----------------------------------------|--------------------------------------------|
|
|
138
|
+
| `{{ toc }}` | a live Word TOC field | a table of contents rebuilt by md2doc |
|
|
139
|
+
| `{{ pages }}` | a live `NUMPAGES` field | a live `text:page-count` field |
|
|
140
|
+
|
|
141
|
+
An existing ADEME-styled `text:table-of-content` element is also filled (its
|
|
142
|
+
cached entries are replaced), so an ODT template that already contains a
|
|
143
|
+
sommaire keeps its exact look.
|
|
144
|
+
|
|
145
|
+
### Custom styles and table theme
|
|
146
|
+
|
|
147
|
+
For ODT templates an optional styles file makes everything explicit and keepable
|
|
148
|
+
next to the template (pass it with `--styles`):
|
|
149
|
+
|
|
150
|
+
```xml
|
|
151
|
+
<md2doc-styles xmlns:style="…" xmlns:fo="…">
|
|
152
|
+
<!-- redirect a pandoc style to one the template already has -->
|
|
153
|
+
<md2doc-rename from="Heading_20_1" to="Titre_20_1"/>
|
|
154
|
+
|
|
155
|
+
<!-- add or override a named style -->
|
|
156
|
+
<style:style style:name="Text_20_body" style:family="paragraph"
|
|
157
|
+
style:parent-style-name="Normal"/>
|
|
158
|
+
|
|
159
|
+
<!-- promote a paragraph style to a TOC heading -->
|
|
160
|
+
<md2doc-toc-heading style="titre_20_SANS_20_NUMEROTATION" level="1"/>
|
|
161
|
+
|
|
162
|
+
<!-- borders and header fill for pandoc's automatic table cells -->
|
|
163
|
+
<md2doc-table border="#810F3F" header-bg="#810F3F" header-fg="#FFFFFF"/>
|
|
164
|
+
</md2doc-styles>
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
All elements are optional. `<md2doc-rename>` is preferred over an alias style
|
|
168
|
+
when the template's own style drives chapter numbering: an alias with the same
|
|
169
|
+
outline level makes LibreOffice drop it.
|
|
170
|
+
|
|
171
|
+
### Customising it
|
|
172
|
+
|
|
173
|
+
Open the template in Word or LibreOffice and edit it like any document:
|
|
174
|
+
|
|
175
|
+
- restyle `Normal`, `Title`, `Heading 1`, `Caption`, … — the body follows;
|
|
176
|
+
- change the page size, margins, header and footer;
|
|
177
|
+
- edit the front matter, keeping or moving the `{{ ... }}` fields.
|
|
178
|
+
|
|
179
|
+
Save it back and re-run `md2doc`. Nothing else to configure.
|
|
180
|
+
|
|
181
|
+
## Command-line reference
|
|
182
|
+
|
|
183
|
+
```
|
|
184
|
+
md2doc INPUT.md [-o OUT] [-t TEMPLATE] [--styles STYLES.xml]
|
|
185
|
+
[--back BACK] [--no-cover] [--toc] [--toc-depth N]
|
|
186
|
+
[--pdf] [--keep]
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
| Option | Effect |
|
|
190
|
+
|--------------------|---------------------------------------------------------------|
|
|
191
|
+
| `-o`, `--output` | output file (default: next to the input, with the template's extension) |
|
|
192
|
+
| `-t`, `--template` | template (`.docx` or `.odt`; default: bundled `template.docx`) |
|
|
193
|
+
| `--styles` | explicit custom styles + table theme (ODT) |
|
|
194
|
+
| `--back` | document appended after the body (ODT: spliced at `{{ back }}`)|
|
|
195
|
+
| `--no-cover` | styles only; keep pandoc's title block (DOCX only) |
|
|
196
|
+
| `--toc` | build a table of contents |
|
|
197
|
+
| `--toc-depth` | heading levels kept in the TOC (default: 3) |
|
|
198
|
+
| `--pdf` | also export a PDF with LibreOffice |
|
|
199
|
+
| `--keep` | keep the intermediate `build/` files |
|
|
200
|
+
|
|
201
|
+
## Notes and limits
|
|
202
|
+
|
|
203
|
+
- **ODT table of contents** — LibreOffice does not update indexes in
|
|
204
|
+
`--headless` mode. `md2doc` therefore fills the entries itself and runs a
|
|
205
|
+
**two-pass** build: render once to locate each heading in the PDF, then render
|
|
206
|
+
again with the page numbers filled in. `--pdf` is what enables the second pass.
|
|
207
|
+
- **DOCX table of contents** — pandoc inserts a real Word TOC *field*. It is
|
|
208
|
+
empty until the reader updates it; Word does so on open (pandoc sets the
|
|
209
|
+
"update fields" flag). In LibreOffice, use *Tools ▸ Update ▸ Indexes and
|
|
210
|
+
tables* if the PDF shows it blank.
|
|
211
|
+
- **Images** — relative paths in the Markdown resolve against the working
|
|
212
|
+
directory, so run `md2doc` from the project root. Images wider than the
|
|
213
|
+
template's text area are scaled down to fit, keeping their aspect ratio.
|
|
214
|
+
- **ODF style names** — spaces in style names are encoded as `_20_`. Pandoc
|
|
215
|
+
passes `custom-style` values verbatim, so md2doc encodes them before splicing.
|
|
216
|
+
- **Bullets render blank in LibreOffice / OnlyOffice** — pandoc marks its DOCX
|
|
217
|
+
bullets with the Word *Symbol* font (U+F0B7). On a machine without Symbol,
|
|
218
|
+
readers show nothing. `md2doc` rewrites them to a plain `•` automatically.
|
|
219
|
+
- **Complex fixed pages** (multi-column back matter, designed back covers, text
|
|
220
|
+
boxes) are not produced by Markdown. Keep such pages in the template, or pass
|
|
221
|
+
them as a separate `.odt`/`.docx` to `--back`.
|
|
222
|
+
|
|
223
|
+
## Layout
|
|
224
|
+
|
|
225
|
+
```
|
|
226
|
+
md2doc/
|
|
227
|
+
pyproject.toml package metadata (distribution: markdown2word)
|
|
228
|
+
requirements.txt Python dependencies
|
|
229
|
+
scripts/make_assets.py builds the bundled default template
|
|
230
|
+
src/md2doc/
|
|
231
|
+
cli.py argument parsing, format dispatch, two-pass TOC
|
|
232
|
+
frontmatter.py YAML front matter and placeholder context
|
|
233
|
+
pandoc.py pandoc / LibreOffice wrappers
|
|
234
|
+
docx.py DOCX backend
|
|
235
|
+
odt.py ODT backend
|
|
236
|
+
assets/template.docx styles + cover (generated; edit freely)
|
|
237
|
+
assets/reference.odt pandoc's stock ODT styles, merged on demand
|
|
238
|
+
examples/rapport.md sample source
|
|
239
|
+
tests/ unit tests
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
## A worked example
|
|
243
|
+
|
|
244
|
+
The openpv repository shows the ODT path end to end — splitting a delivered
|
|
245
|
+
report into a reusable front/back template and rebuilding it from Markdown —
|
|
246
|
+
under `doc/livrables/pu10/md2doc/`.
|
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
# md2doc — Markdown + a Word/ODT template → a styled document
|
|
2
|
+
|
|
3
|
+
`md2doc` turns a Markdown file with a YAML header into a real `.docx` or `.odt`,
|
|
4
|
+
built on your own template. It is meant for the common split: you write in plain
|
|
5
|
+
text, your colleagues review in Word or LibreOffice.
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
Report.md + template.docx ──► Report.docx (──► Report.pdf)
|
|
9
|
+
Report.md + template.odt ──► Report.odt (──► Report.pdf)
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## Why
|
|
13
|
+
|
|
14
|
+
Markdown is quick to write, diffs cleanly and stays readable in a git
|
|
15
|
+
repository. Word is what reviewers, managers and clients actually open, comment
|
|
16
|
+
on and print. `md2doc` keeps the source in Markdown while producing a document
|
|
17
|
+
that is 100 % native: real styles, real headings, real tables, a real cover page
|
|
18
|
+
— not a text dump pasted into a blank file.
|
|
19
|
+
|
|
20
|
+
The output format is the template's own: give a `.docx` template and you get a
|
|
21
|
+
`.docx`, give an `.odt` template and you get an `.odt`. Use `.odt` when the
|
|
22
|
+
template comes from LibreOffice and must keep features that a
|
|
23
|
+
Word round-trip would flatten (frames, columns, a designed table of contents,
|
|
24
|
+
an existing back cover).
|
|
25
|
+
|
|
26
|
+
## Requirements
|
|
27
|
+
|
|
28
|
+
- [pandoc](https://pandoc.org) 3.x — the conversion engine.
|
|
29
|
+
- Python 3.9+ with the packages in `requirements.txt`.
|
|
30
|
+
- LibreOffice (`soffice`) — only for the optional `--pdf` export, and always for
|
|
31
|
+
the ODT table-of-contents pass.
|
|
32
|
+
|
|
33
|
+
## Install
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
pip install markdown2word # installs the `md2doc` command
|
|
37
|
+
# or, from a clone:
|
|
38
|
+
uv venv .venv && uv pip install --python .venv/bin/python -r requirements.txt
|
|
39
|
+
PYTHONPATH=src .venv/bin/python -m md2doc.cli --help
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`scripts/make_assets.py` regenerates the bundled default template
|
|
43
|
+
(`src/md2doc/assets/template.docx`) from pandoc's own reference document. You
|
|
44
|
+
only need it if you want to rebuild the stock template.
|
|
45
|
+
|
|
46
|
+
## The Markdown file
|
|
47
|
+
|
|
48
|
+
The file starts with a YAML front matter between `---` lines:
|
|
49
|
+
|
|
50
|
+
```yaml
|
|
51
|
+
---
|
|
52
|
+
title: Rapport d'exemple
|
|
53
|
+
tagline: OPEN-PV : outil paramétré
|
|
54
|
+
subtitle: PU 10 : comparaison des bases
|
|
55
|
+
author:
|
|
56
|
+
- Camille Dupont
|
|
57
|
+
- Raphaël Jolivet
|
|
58
|
+
date: Juillet 2026
|
|
59
|
+
year: 2026 # optional; read from `date` otherwise
|
|
60
|
+
contract: 2025AC000028
|
|
61
|
+
lang: fr-FR
|
|
62
|
+
toc: true # insert a table of contents
|
|
63
|
+
---
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Recognised keys (all become `{{ placeholders }}` in the template):
|
|
67
|
+
|
|
68
|
+
| Key | Role |
|
|
69
|
+
|------------|-------------------------------------------------------------------|
|
|
70
|
+
| `title` | document title |
|
|
71
|
+
| `tagline` | programme / collection tagline |
|
|
72
|
+
| `subtitle` | document subtitle |
|
|
73
|
+
| `author` | one name or a list; joined with commas |
|
|
74
|
+
| `date` | date (defaults to today) |
|
|
75
|
+
| `year` | year; taken from a 4-digit number found in `date` otherwise |
|
|
76
|
+
| `contract` | contract number |
|
|
77
|
+
| `lang` | document language (e.g. `fr-FR`); drives the spell checker |
|
|
78
|
+
| `toc` | `true` builds the table of contents (same as `--toc`) |
|
|
79
|
+
|
|
80
|
+
Any other scalar key is exposed to the template too. The keys above are
|
|
81
|
+
*consumed*: they are removed from what is handed to pandoc, so they do not leak
|
|
82
|
+
into the body.
|
|
83
|
+
|
|
84
|
+
For ODT, `lang` sets the language on the default paragraph/character styles and
|
|
85
|
+
writes `<dc:language>` in the document metadata, which is what LibreOffice's
|
|
86
|
+
spell checker reads.
|
|
87
|
+
|
|
88
|
+
The body is ordinary pandoc Markdown: headings, lists (bullet and numbered),
|
|
89
|
+
**bold**, *italic*, `inline code`, fenced code blocks, block quotes, tables,
|
|
90
|
+
images (``), footnotes (`[^1]`) and links. Each one maps
|
|
91
|
+
to a native style, so reviewers can restyle the whole document at once.
|
|
92
|
+
|
|
93
|
+
## The template — what it does
|
|
94
|
+
|
|
95
|
+
A template is a normal `.docx` or `.odt` with two jobs:
|
|
96
|
+
|
|
97
|
+
1. **Styles** — pandoc uses it as its style reference: paragraph and character
|
|
98
|
+
styles, page size, margins, headers and footers. The template is meant to be
|
|
99
|
+
**self-sufficient**: it should carry every style the body needs, so no
|
|
100
|
+
separate style file is required.
|
|
101
|
+
2. **Front matter and back matter** — for DOCX its body is rendered with
|
|
102
|
+
[docxtpl](https://docxtpl.readthedocs.io) from the front matter (cover,
|
|
103
|
+
résumé, abstract…). For ODT the body is read as-is and the Markdown body is
|
|
104
|
+
spliced where a `{{ body }}` marker sits, and an optional `--back` document
|
|
105
|
+
where `{{ back }}` sits.
|
|
106
|
+
|
|
107
|
+
Put any `{{ placeholder }}` you like in the front matter: `{{ title }}`,
|
|
108
|
+
`{{ subtitle }}`, `{{ authors }}`, `{{ date }}`, plus any extra front-matter
|
|
109
|
+
key. Two placeholders are special:
|
|
110
|
+
|
|
111
|
+
| Placeholder | DOCX | ODT |
|
|
112
|
+
|-------------|----------------------------------------|--------------------------------------------|
|
|
113
|
+
| `{{ toc }}` | a live Word TOC field | a table of contents rebuilt by md2doc |
|
|
114
|
+
| `{{ pages }}` | a live `NUMPAGES` field | a live `text:page-count` field |
|
|
115
|
+
|
|
116
|
+
An existing ADEME-styled `text:table-of-content` element is also filled (its
|
|
117
|
+
cached entries are replaced), so an ODT template that already contains a
|
|
118
|
+
sommaire keeps its exact look.
|
|
119
|
+
|
|
120
|
+
### Custom styles and table theme
|
|
121
|
+
|
|
122
|
+
For ODT templates an optional styles file makes everything explicit and keepable
|
|
123
|
+
next to the template (pass it with `--styles`):
|
|
124
|
+
|
|
125
|
+
```xml
|
|
126
|
+
<md2doc-styles xmlns:style="…" xmlns:fo="…">
|
|
127
|
+
<!-- redirect a pandoc style to one the template already has -->
|
|
128
|
+
<md2doc-rename from="Heading_20_1" to="Titre_20_1"/>
|
|
129
|
+
|
|
130
|
+
<!-- add or override a named style -->
|
|
131
|
+
<style:style style:name="Text_20_body" style:family="paragraph"
|
|
132
|
+
style:parent-style-name="Normal"/>
|
|
133
|
+
|
|
134
|
+
<!-- promote a paragraph style to a TOC heading -->
|
|
135
|
+
<md2doc-toc-heading style="titre_20_SANS_20_NUMEROTATION" level="1"/>
|
|
136
|
+
|
|
137
|
+
<!-- borders and header fill for pandoc's automatic table cells -->
|
|
138
|
+
<md2doc-table border="#810F3F" header-bg="#810F3F" header-fg="#FFFFFF"/>
|
|
139
|
+
</md2doc-styles>
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
All elements are optional. `<md2doc-rename>` is preferred over an alias style
|
|
143
|
+
when the template's own style drives chapter numbering: an alias with the same
|
|
144
|
+
outline level makes LibreOffice drop it.
|
|
145
|
+
|
|
146
|
+
### Customising it
|
|
147
|
+
|
|
148
|
+
Open the template in Word or LibreOffice and edit it like any document:
|
|
149
|
+
|
|
150
|
+
- restyle `Normal`, `Title`, `Heading 1`, `Caption`, … — the body follows;
|
|
151
|
+
- change the page size, margins, header and footer;
|
|
152
|
+
- edit the front matter, keeping or moving the `{{ ... }}` fields.
|
|
153
|
+
|
|
154
|
+
Save it back and re-run `md2doc`. Nothing else to configure.
|
|
155
|
+
|
|
156
|
+
## Command-line reference
|
|
157
|
+
|
|
158
|
+
```
|
|
159
|
+
md2doc INPUT.md [-o OUT] [-t TEMPLATE] [--styles STYLES.xml]
|
|
160
|
+
[--back BACK] [--no-cover] [--toc] [--toc-depth N]
|
|
161
|
+
[--pdf] [--keep]
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
| Option | Effect |
|
|
165
|
+
|--------------------|---------------------------------------------------------------|
|
|
166
|
+
| `-o`, `--output` | output file (default: next to the input, with the template's extension) |
|
|
167
|
+
| `-t`, `--template` | template (`.docx` or `.odt`; default: bundled `template.docx`) |
|
|
168
|
+
| `--styles` | explicit custom styles + table theme (ODT) |
|
|
169
|
+
| `--back` | document appended after the body (ODT: spliced at `{{ back }}`)|
|
|
170
|
+
| `--no-cover` | styles only; keep pandoc's title block (DOCX only) |
|
|
171
|
+
| `--toc` | build a table of contents |
|
|
172
|
+
| `--toc-depth` | heading levels kept in the TOC (default: 3) |
|
|
173
|
+
| `--pdf` | also export a PDF with LibreOffice |
|
|
174
|
+
| `--keep` | keep the intermediate `build/` files |
|
|
175
|
+
|
|
176
|
+
## Notes and limits
|
|
177
|
+
|
|
178
|
+
- **ODT table of contents** — LibreOffice does not update indexes in
|
|
179
|
+
`--headless` mode. `md2doc` therefore fills the entries itself and runs a
|
|
180
|
+
**two-pass** build: render once to locate each heading in the PDF, then render
|
|
181
|
+
again with the page numbers filled in. `--pdf` is what enables the second pass.
|
|
182
|
+
- **DOCX table of contents** — pandoc inserts a real Word TOC *field*. It is
|
|
183
|
+
empty until the reader updates it; Word does so on open (pandoc sets the
|
|
184
|
+
"update fields" flag). In LibreOffice, use *Tools ▸ Update ▸ Indexes and
|
|
185
|
+
tables* if the PDF shows it blank.
|
|
186
|
+
- **Images** — relative paths in the Markdown resolve against the working
|
|
187
|
+
directory, so run `md2doc` from the project root. Images wider than the
|
|
188
|
+
template's text area are scaled down to fit, keeping their aspect ratio.
|
|
189
|
+
- **ODF style names** — spaces in style names are encoded as `_20_`. Pandoc
|
|
190
|
+
passes `custom-style` values verbatim, so md2doc encodes them before splicing.
|
|
191
|
+
- **Bullets render blank in LibreOffice / OnlyOffice** — pandoc marks its DOCX
|
|
192
|
+
bullets with the Word *Symbol* font (U+F0B7). On a machine without Symbol,
|
|
193
|
+
readers show nothing. `md2doc` rewrites them to a plain `•` automatically.
|
|
194
|
+
- **Complex fixed pages** (multi-column back matter, designed back covers, text
|
|
195
|
+
boxes) are not produced by Markdown. Keep such pages in the template, or pass
|
|
196
|
+
them as a separate `.odt`/`.docx` to `--back`.
|
|
197
|
+
|
|
198
|
+
## Layout
|
|
199
|
+
|
|
200
|
+
```
|
|
201
|
+
md2doc/
|
|
202
|
+
pyproject.toml package metadata (distribution: markdown2word)
|
|
203
|
+
requirements.txt Python dependencies
|
|
204
|
+
scripts/make_assets.py builds the bundled default template
|
|
205
|
+
src/md2doc/
|
|
206
|
+
cli.py argument parsing, format dispatch, two-pass TOC
|
|
207
|
+
frontmatter.py YAML front matter and placeholder context
|
|
208
|
+
pandoc.py pandoc / LibreOffice wrappers
|
|
209
|
+
docx.py DOCX backend
|
|
210
|
+
odt.py ODT backend
|
|
211
|
+
assets/template.docx styles + cover (generated; edit freely)
|
|
212
|
+
assets/reference.odt pandoc's stock ODT styles, merged on demand
|
|
213
|
+
examples/rapport.md sample source
|
|
214
|
+
tests/ unit tests
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
## A worked example
|
|
218
|
+
|
|
219
|
+
The openpv repository shows the ODT path end to end — splitting a delivered
|
|
220
|
+
report into a reusable front/back template and rebuilding it from Markdown —
|
|
221
|
+
under `doc/livrables/pu10/md2doc/`.
|
|
Binary file
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Rapport d'exemple
|
|
3
|
+
subtitle: Pipeline Markdown -> Word
|
|
4
|
+
author:
|
|
5
|
+
- Camille Dupont
|
|
6
|
+
- Raphaël Jolivet
|
|
7
|
+
date: 2026-11-18
|
|
8
|
+
lang: fr-FR
|
|
9
|
+
toc: true
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
# Introduction
|
|
13
|
+
|
|
14
|
+
Ce document est produit par **md2doc** à partir de ce fichier Markdown et du
|
|
15
|
+
gabarit Word `assets/template.docx`. La page de couverture est remplie grâce au
|
|
16
|
+
*front matter* YAML ci-dessus.
|
|
17
|
+
|
|
18
|
+
Les titres, listes, tableaux, images, notes et blocs de code sont convertis en
|
|
19
|
+
styles Word natifs, éditables et modifiables par les relecteurs.
|
|
20
|
+
|
|
21
|
+
## Objectifs
|
|
22
|
+
|
|
23
|
+
1. mêler la simplicité de Markdown à la robustesse d'un gabarit Word ;
|
|
24
|
+
2. produire un `.docx` que des collègues sous Word peuvent commenter et
|
|
25
|
+
modifier au suivi des modifications ;
|
|
26
|
+
3. exporter un PDF pour la diffusion.
|
|
27
|
+
|
|
28
|
+
## Liste à puces
|
|
29
|
+
|
|
30
|
+
- première puce ;
|
|
31
|
+
- deuxième puce, avec du `code inline` ;
|
|
32
|
+
- troisième puce.
|
|
33
|
+
|
|
34
|
+
# Résultats
|
|
35
|
+
|
|
36
|
+
Le tableau suivant utilise un style Word natif.
|
|
37
|
+
|
|
38
|
+
| Catégorie | Valeur | Unité |
|
|
39
|
+
|-----------|-------:|:------|
|
|
40
|
+
| Climat | 0,74 | kg CO₂-éq / kWh |
|
|
41
|
+
| Eau | 0,49 | m³ deprivé / kWh |
|
|
42
|
+
| Sols | 0,88 | Pt |
|
|
43
|
+
|
|
44
|
+
> Une citation en bloc, utile pour une définition ou un avertissement.
|
|
45
|
+
|
|
46
|
+
Une note de bas de page.[^1]
|
|
47
|
+
|
|
48
|
+
[^1]: Le texte de la note apparaît en bas de page, au format Word.
|
|
49
|
+
|
|
50
|
+
```python
|
|
51
|
+
def impacts(background):
|
|
52
|
+
return {method: value for method, value in background.items()}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
# Conclusion
|
|
56
|
+
|
|
57
|
+
Ce squelette suffit pour la plupart des rapports : il ne reste qu'à adapter le
|
|
58
|
+
gabarit (polices, couleurs, en-têtes, pieds de page) dans Word.
|
|
Binary file
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "markdown2word"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Markdown + YAML front matter + a Word/ODT template -> styled document"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.9"
|
|
11
|
+
license = { text = "MIT" }
|
|
12
|
+
authors = [{ name = "Raphaël Jolivet" }]
|
|
13
|
+
keywords = ["markdown", "pandoc", "docx", "odt", "template", "opendocument"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 3 - Alpha",
|
|
16
|
+
"Environment :: Console",
|
|
17
|
+
"Intended Audience :: End Users/Desktop",
|
|
18
|
+
"License :: OSI Approved :: MIT License",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Topic :: Text Processing :: Markup",
|
|
21
|
+
]
|
|
22
|
+
dependencies = [
|
|
23
|
+
"python-docx>=1.1",
|
|
24
|
+
"pyyaml>=6.0",
|
|
25
|
+
"docxtpl>=0.18",
|
|
26
|
+
"docxcompose>=1.4",
|
|
27
|
+
"lxml>=4.9",
|
|
28
|
+
]
|
|
29
|
+
|
|
30
|
+
[project.optional-dependencies]
|
|
31
|
+
dev = ["pytest>=7.0"]
|
|
32
|
+
|
|
33
|
+
[project.scripts]
|
|
34
|
+
md2doc = "md2doc.cli:main"
|
|
35
|
+
|
|
36
|
+
[project.urls]
|
|
37
|
+
Source = "https://git.sophia.minesparis.psl.eu/rjolivet/md2doc"
|
|
38
|
+
|
|
39
|
+
[tool.hatch.build.targets.wheel]
|
|
40
|
+
packages = ["src/md2doc"]
|
|
41
|
+
|
|
42
|
+
[tool.pytest.ini_options]
|
|
43
|
+
pythonpath = ["src"]
|
|
44
|
+
testpaths = ["tests"]
|