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.
@@ -0,0 +1,7 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ build/
5
+ dist/
6
+ *.egg-info/
7
+ .pytest_cache/
@@ -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 (`![caption](figure.png)`), 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 (`![caption](figure.png)`), 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/`.
@@ -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"]