Markdown → compliant Word
This file is the router. The engine is deterministic: the same manuscript and the same format
requirements always produce a byte-identical .docx. Do not substitute a hand-written
python-docx script; run the installed pipeline.
Before the first export in a session, confirm the engine is available: md-to-word --version
must print a version. The export engine is installed separately; if the command is missing, install it
with pip install md-to-word-docx, then run the check again.
The full vocabulary lives in the manual inside the package, not here. md-to-word --contract
prints its absolute path (Chinese or English, following the manuscript). Everything below is order
of work; every spelling is looked up in the manual.
1. Decide the scenario first
| Scenario |
What the user says |
What to do |
| Journal or school compliance |
"format it using these journal instructions" |
Read format-requirements; extract requirements from PDF, Word, images or pasted text, then build the engine requirements file. |
| Reference-paper reformatting |
"format manuscript A like paper B" |
Read reference-layout; inspect actual reference paragraphs, map their roles, then extract and verify the requirements. |
| Existing requirements |
"use our lab's spec file" |
Pass it with -r. |
| Baseline export (no explicit spec) |
"turn this into a Word file" |
Normalize the manuscript to the contract, then export with the built-in preset. The preset is a complete, valid format, not a provisional default. |
Input format and purpose are separate: a Word or PDF may contain written submission rules,
a template or an example paper. Read explicit requirements as text; inspect example layout
when needed. Automatically read images and scanned pages with available image-reading or OCR
tools, checking the recognized rules against the image. Handle mixed documents page by page.
The host performs this intake; the paragraph-sample helper accepts DOCX only.
State the chosen preset or requirements path in one line, then proceed. Without -r the only file
picked up is one named exactly format.txt beside the manuscript; no other .txt is guessed at
(if one is there, the run names it in a reminder). With no format.txt, the preset follows the
manuscript's language: zh-academic for Chinese, en-nature for everything else. The run reports
which one it used.
No path accepts arbitrary Markdown and returns a finished document: a preset supplies formatting,
not missing structure. When the manuscript violates the contract, pre-flight stops with a line
number rather than emitting a document that looks acceptable while its formatting was never mapped.
2. Bring the manuscript to the input contract
The source may be pasted text, .txt, .md, an old .docx, or a PDF. Normalize it to Markdown
first; never edit the user's original file in place. For a reference-paper request, identify source
and reference roles separately using the linked workflow before normalization. Existing DOCX
objects are reconstructed by export; check their content rather than assuming native preservation.
- Headings:
#, ##, ###, consecutive and unskipped; a heading that carries its own number
(1., 2.1) needs as many # as its number has levels.
- Paragraph styles: a line starting with
%% sets that paragraph's style —
%% Abstract …, %% Table Caption **Table 1** …, %% Image Caption Figure 1 ….
One line is one paragraph, ended by a blank line, with no closing fence. Style names come from a
closed list (manual §3.4) in either language; heading levels are set by # only.
- Title, author, abstract, keywords are style lines in the body, never YAML — their position on
the page is the author's decision, and YAML has no position. Pre-flight blocks those keys with the
exact line to write instead.
- Paragraphs: one line is one paragraph; consecutive lines are never joined, so a file of short
one-sentence paragraphs is already correct. For a break inside one paragraph (an address, verse,
a long title), end the line with a backslash or two spaces — it becomes a line break within the same
paragraph. Suspected wrapping is reported as a grouped warning with the line numbers.
- YAML holds only position-independent configuration:
bibliography:, csl:, crossref:,
link-citations:.
- Equations:
$$...$$ {#eq-name} on its own line, referenced as @eq-name. Chinese manuscripts
get 「式/图/表」 prefixes and (1)numbering, English ones get Equation/Figure/Table and (1). Add
crossref: chapters: true for per-chapter numbering. \tag{} is blocked.
- Citations:
[@key] parenthetical, @key narrative, from bibliography: + csl:. A .bib is
mandatory once the manuscript cites: handwritten reference lists are not supported, and [@key]
without bibliography: would be printed literally.
- Figures and tables:
{width=13cm} with the caption in its own
%% Image Caption / %% 图片题注 paragraph; table caption above, note below. Do not put
{#fig-...} labels on images. Column widths follow the separator row's dash lengths.
- Block markers (three, each on its own line with blank lines around):
{{< pagebreak >}},
{{< toc >}}, {{< section page_number=lowerRoman start=1 >}} (Chinese parameters 页码= 起始=
also work). The section marker closes the section above it; never add a page break next to it.
- Unsupported Markdown is blocked with a replacement, never printed literally: HTML tags,
---
rules, ==== headings, definition lists, - [ ] boxes, tables without outer pipes, nested block
quotes, full-width %%, four-space code blocks, a second paragraph inside a
list item, ==highlight==, [text]{.class} (except .underline), \(...\) inline math, and a
percentage image width ({width=60%} — write an absolute length).
3. Choose or build the format requirements
- Starting from nothing —
md-to-word init writes a complete preset copy plus a one-page
manuscript that exports as-is.
- Built-in preset —
zh-academic or en-nature. Use as-is when the user gave no detailed spec.
- Copy and edit a preset — change only the lines the user mentioned. Field order is fixed:
font, size, bold, italic, alignment, line spacing, space before, space after, indent. Every style
line must be complete; missing fields are errors.
- Reverse-engineer a target
.docx — md-to-word-template target.docx -o format.txt, then
review the "to confirm" list at the end of the draft. This reads known style definitions;
reference papers using custom styles or direct formatting need the paragraph-sample workflow
in reference-layout.
- Written journal requirements — extract the rules using
format-requirements, then translate supported properties
into the engine vocabulary. Keep stated requirements separate from inferred sample layout.
Each property has exactly one accepted spelling (two in total: the canonical Chinese and English
forms); anything else is a hard error with a line number. Full table: manual §3.1. Style names:
§3.4. Presets are the reference examples — md-to-word --contract prints their paths.
Throughout this file, format.txt means the format requirements file — any path works, -r takes
it.
Citation style comes from csl: with a bundled file name (manual §7) or a path to the user's own
CSL. Without csl:, Chinese manuscripts get GB/T 7714 numeric, others APA 7th. A user-supplied CSL
is normalized on export so that one requirements file always produces one layout.
4. Export
Run the installed command from the manuscript's directory:
md-to-word manuscript.md -o manuscript.docx
md-to-word manuscript.md -r format.txt -o manuscript.docx
md-to-word --contract # contract + paths to the manual and presets
The pipeline runs: pre-flight validation → style template generation → manuscript model → OOXML
writing → number-integrity check → line-by-line audit against the requirements file.
5. How to read the gates
Two levels, split by "would the mistake be visible afterwards":
- Blocking — silently wrong later: dropped content, syntax printed literally, formatting never
mapped, a title in YAML, a caption inside an image's brackets. Fix the reported line; do not reach
for
--no-check, which turns off the blocking gates too.
- Warning — visible but non-compliant: an image wider than the text block (it gets clamped), a
caption far from its figure, a skipped heading level, a page break after a section marker,
suspected line wrapping. Warnings of one kind arrive as a single line (up to eight line numbers,
then a count).
Add --json when the result has to be read back programmatically: stdout then carries one JSON
object — ok, returncode, input, output, pdf, lang, messages, errors — with progress
and reminders on stderr. The keys are fixed; the sentences inside them follow the manuscript's
language, and the reminders are in messages.
Exit codes: 0 every gate passed; 1 manuscript, gate or dependency problem; 2 a usage error
(bad flags or a missing argument); 3 the .docx was written but the optional --pdf proof was
skipped (non-macOS). Messages follow the manuscript's language. Add --verbose when a format does
not seem to take effect.
6. Verify before delivery
- For reference-paper requests, first verify role and property coverage against the reference
samples as described in reference-layout. A successful export
checks the supplied requirements, not whether they fully describe the reference paper.
- For supplied instructions, compare the output against the original clauses and their page,
paragraph or image locations, including recognized numbers and units. Report requirements
the engine cannot apply separately from those verified by its export checks.
- Confirm the
.docx exists and the command exited 0.
- Report the applied preset or requirements file, the citation style, and anything the run warned
about.
- Say plainly that the layout still needs a manual check in Word. The engine verifies text and
structure; row heights, column widths and where equations and captions settle are only visible in
a real renderer.
- When the document has a TOC,
{style-title} headers or per-section page numbers, run once with
--pdf (macOS with Word) — that is the only way fields are expanded — and spot-check the first
page, the widest table, an equation-heavy page and the references.
7. Boundaries
- No custom cover pages, merged cells, multi-column text, inline text colour, or text-wrapped
figures. Export the body, then complete those in Word.
- Only equation cross-references are supported (
{#eq-x} + @eq-x); figure and table numbers are
typed into the caption.
- Sum and integral limits stay on the right of the symbol in numbered equations (Word stacks limits
only in display math). Content and symbols are correct; only the arrangement differs.
- TOC page numbers and chapter headers are Word fields; Word asks once whether to update them.
Full statements: manual §6 (limits) and §8 (symptom → fix).
8. Related skills
This skill compiles the manuscript; these cover the steps around it. Hand off rather than
re-implement:
| Skill |
What it covers |
nature-writing |
Drafting the manuscript and its section-level argument (input to this one) |
nature-polishing |
Language polishing and academic phrasing (input to this one) |
nature-citation |
Searching for and exporting reference entries (RIS / ENW / Zotero RDF); export BibTeX from the reference manager for the .bib this skill consumes |
nature-ref-verifier |
Cross-checking reference metadata before submission |
nature-paper2ppt |
Turning the same manuscript into a presentation deck |
Upstream engine, the general-purpose pip package, and the changelog:
md-to-word.
1---2name: nature-paper2word3description: "Compile an academic Markdown manuscript into a journal- or school-compliant Word (.docx): declared typography, native OMML equations, three-line tables, cross-references, per-section page numbers, CSL bibliographies (GB/T 7714, APA, Nature, IEEE), and pre/post-export quality gates. 把学术论文的 Markdown 稿件导出为符合期刊或学位论文规范的 Word:摘要、公式编号、三线表、题注、交叉引用、目录域、参考文献。Use when the user wants a submission-ready .docx — 论文转 Word、学位论文排版、期刊投稿排版、prepare submission docx — or a readable copy of a manuscript. Not for PDF, HTML or LaTeX output, and not for slide decks or grant forms. Also use for reference-paper reformatting and format requirements supplied as PDF, Word, images or pasted text, with automatic image-text recognition. 参考论文样式提取、按参考文档重排版、期刊排版要求、图片与扫描件识别。"4license: MIT5metadata:6 source: https://skillmd.com/skills/fridrichmethod/nature-paper2word7---89# Markdown → compliant Word1011This file is the router. The engine is deterministic: the same manuscript and the same format12requirements always produce a byte-identical `.docx`. Do not substitute a hand-written13python-docx script; run the installed pipeline.1415**Before the first export in a session, confirm the engine is available**: `md-to-word --version`16must print a version. The export engine is installed separately; if the command is missing, install it17with `pip install md-to-word-docx`, then run the check again.1819**The full vocabulary lives in the manual inside the package**, not here. `md-to-word --contract`20prints its absolute path (Chinese or English, following the manuscript). Everything below is order21of work; every spelling is looked up in the manual.2223## 1. Decide the scenario first2425| Scenario | What the user says | What to do |26|---|---|---|27| Journal or school compliance | "format it using these journal instructions" | Read [format-requirements](references/format-requirements.md); extract requirements from PDF, Word, images or pasted text, then build the engine requirements file. |28| Reference-paper reformatting | "format manuscript A like paper B" | Read [reference-layout](references/reference-layout.md); inspect actual reference paragraphs, map their roles, then extract and verify the requirements. |29| Existing requirements | "use our lab's spec file" | Pass it with `-r`. |30| Baseline export (no explicit spec) | "turn this into a Word file" | Normalize the manuscript to the contract, then export with the built-in preset. The preset is a complete, valid format, not a provisional default. |3132Input format and purpose are separate: a Word or PDF may contain written submission rules,33a template or an example paper. Read explicit requirements as text; inspect example layout34when needed. Automatically read images and scanned pages with available image-reading or OCR35tools, checking the recognized rules against the image. Handle mixed documents page by page.36The host performs this intake; the paragraph-sample helper accepts DOCX only.3738State the chosen preset or requirements path in one line, then proceed. Without `-r` the only file39picked up is one named exactly **`format.txt`** beside the manuscript; no other `.txt` is guessed at40(if one is there, the run names it in a reminder). With no `format.txt`, the preset follows the41**manuscript's language**: `zh-academic` for Chinese, `en-nature` for everything else. The run reports42which one it used.4344No path accepts arbitrary Markdown and returns a finished document: a preset supplies formatting,45not missing structure. When the manuscript violates the contract, pre-flight stops with a line46number rather than emitting a document that looks acceptable while its formatting was never mapped.4748## 2. Bring the manuscript to the input contract4950The source may be pasted text, `.txt`, `.md`, an old `.docx`, or a PDF. Normalize it to Markdown51first; never edit the user's original file in place. For a reference-paper request, identify source52and reference roles separately using the linked workflow before normalization. Existing DOCX53objects are reconstructed by export; check their content rather than assuming native preservation.5455- **Headings**: `#`, `##`, `###`, consecutive and unskipped; a heading that carries its own number56 (`1.`, `2.1`) needs as many `#` as its number has levels.57- **Paragraph styles**: a line starting with `%% ` sets that paragraph's style —58 `%% Abstract …`, `%% Table Caption **Table 1** …`, `%% Image Caption Figure 1 …`.59 One line is one paragraph, ended by a blank line, with no closing fence. Style names come from a60 closed list (manual §3.4) in either language; heading levels are set by `#` only.61- **Title, author, abstract, keywords** are style lines in the body, never YAML — their position on62 the page is the author's decision, and YAML has no position. Pre-flight blocks those keys with the63 exact line to write instead.64- **Paragraphs**: one line is one paragraph; consecutive lines are never joined, so a file of short65 one-sentence paragraphs is already correct. For a break *inside* one paragraph (an address, verse,66 a long title), end the line with a backslash or two spaces — it becomes a line break within the same67 paragraph. Suspected wrapping is reported as a grouped warning with the line numbers.68- **YAML holds only position-independent configuration**: `bibliography:`, `csl:`, `crossref:`,69 `link-citations:`.70- **Equations**: `$$...$$ {#eq-name}` on its own line, referenced as `@eq-name`. Chinese manuscripts71 get 「式/图/表」 prefixes and (1)numbering, English ones get Equation/Figure/Table and (1). Add72 `crossref: chapters: true` for per-chapter numbering. `\tag{}` is blocked.73- **Citations**: `[@key]` parenthetical, `@key` narrative, from `bibliography:` + `csl:`. A `.bib` is74 mandatory once the manuscript cites: handwritten reference lists are not supported, and `[@key]`75 without `bibliography:` would be printed literally.76- **Figures and tables**: `{width=13cm}` with the caption in its own77 `%% Image Caption` / `%% 图片题注` paragraph; table caption above, note below. Do not put78 `{#fig-...}` labels on images. Column widths follow the separator row's dash lengths.79- **Block markers** (three, each on its own line with blank lines around): `{{< pagebreak >}}`,80 `{{< toc >}}`, `{{< section page_number=lowerRoman start=1 >}}` (Chinese parameters `页码=` `起始=`81 also work). The section marker closes *the section above it*; never add a page break next to it.82- **Unsupported Markdown is blocked with a replacement**, never printed literally: HTML tags, `---`83 rules, `====` headings, definition lists, `- [ ]` boxes, tables without outer pipes, nested block84 quotes, full-width `%%`, four-space code blocks, a second paragraph inside a85 list item, `==highlight==`, `[text]{.class}` (except `.underline`), `\(...\)` inline math, and a86 percentage image width (`{width=60%}` — write an absolute length).8788## 3. Choose or build the format requirements89900. **Starting from nothing** — `md-to-word init` writes a complete preset copy plus a one-page91 manuscript that exports as-is.921. **Built-in preset** — `zh-academic` or `en-nature`. Use as-is when the user gave no detailed spec.932. **Copy and edit a preset** — change only the lines the user mentioned. Field order is fixed:94 font, size, bold, italic, alignment, line spacing, space before, space after, indent. Every style95 line must be complete; missing fields are errors.963. **Reverse-engineer a target `.docx`** — `md-to-word-template target.docx -o format.txt`, then97 review the "to confirm" list at the end of the draft. This reads known style definitions;98 reference papers using custom styles or direct formatting need the paragraph-sample workflow99 in [reference-layout](references/reference-layout.md).1004. **Written journal requirements** — extract the rules using101 [format-requirements](references/format-requirements.md), then translate supported properties102 into the engine vocabulary. Keep stated requirements separate from inferred sample layout.103104Each property has exactly one accepted spelling (two in total: the canonical Chinese and English105forms); anything else is a hard error with a line number. Full table: manual §3.1. Style names:106§3.4. Presets are the reference examples — `md-to-word --contract` prints their paths.107108Throughout this file, `format.txt` means *the format requirements file* — any path works, `-r` takes109it.110111Citation style comes from `csl:` with a bundled file name (manual §7) or a path to the user's own112CSL. Without `csl:`, Chinese manuscripts get GB/T 7714 numeric, others APA 7th. A user-supplied CSL113is normalized on export so that one requirements file always produces one layout.114115## 4. Export116117Run the installed command from the manuscript's directory:118119```bash120md-to-word manuscript.md -o manuscript.docx121md-to-word manuscript.md -r format.txt -o manuscript.docx122md-to-word --contract # contract + paths to the manual and presets123```124125The pipeline runs: pre-flight validation → style template generation → manuscript model → OOXML126writing → number-integrity check → line-by-line audit against the requirements file.127128## 5. How to read the gates129130Two levels, split by "would the mistake be visible afterwards":131132- **Blocking** — silently wrong later: dropped content, syntax printed literally, formatting never133 mapped, a title in YAML, a caption inside an image's brackets. Fix the reported line; do not reach134 for `--no-check`, which turns off the blocking gates too.135- **Warning** — visible but non-compliant: an image wider than the text block (it gets clamped), a136 caption far from its figure, a skipped heading level, a page break after a section marker,137 suspected line wrapping. Warnings of one kind arrive as a single line (up to eight line numbers,138 then a count).139140Add `--json` when the result has to be read back programmatically: stdout then carries one JSON141object — `ok`, `returncode`, `input`, `output`, `pdf`, `lang`, `messages`, `errors` — with progress142and reminders on stderr. The keys are fixed; the sentences inside them follow the manuscript's143language, and the reminders are in `messages`.144145Exit codes: `0` every gate passed; `1` manuscript, gate or dependency problem; `2` a usage error146(bad flags or a missing argument); `3` the `.docx` was written but the optional `--pdf` proof was147skipped (non-macOS). Messages follow the manuscript's language. Add `--verbose` when a format does148not seem to take effect.149150## 6. Verify before delivery151152- For reference-paper requests, first verify role and property coverage against the reference153 samples as described in [reference-layout](references/reference-layout.md). A successful export154 checks the supplied requirements, not whether they fully describe the reference paper.155- For supplied instructions, compare the output against the original clauses and their page,156 paragraph or image locations, including recognized numbers and units. Report requirements157 the engine cannot apply separately from those verified by its export checks.158- Confirm the `.docx` exists and the command exited `0`.159- Report the applied preset or requirements file, the citation style, and anything the run warned160 about.161- Say plainly that the layout still needs a manual check in Word. The engine verifies text and162 structure; row heights, column widths and where equations and captions settle are only visible in163 a real renderer.164- When the document has a TOC, `{style-title}` headers or per-section page numbers, run once with165 `--pdf` (macOS with Word) — that is the only way fields are expanded — and spot-check the first166 page, the widest table, an equation-heavy page and the references.167168## 7. Boundaries169170- No custom cover pages, merged cells, multi-column text, inline text colour, or text-wrapped171 figures. Export the body, then complete those in Word.172- Only equation cross-references are supported (`{#eq-x}` + `@eq-x`); figure and table numbers are173 typed into the caption.174- Sum and integral limits stay on the right of the symbol in numbered equations (Word stacks limits175 only in display math). Content and symbols are correct; only the arrangement differs.176- TOC page numbers and chapter headers are Word fields; Word asks once whether to update them.177Full statements: manual §6 (limits) and §8 (symptom → fix).178179## 8. Related skills180181This skill compiles the manuscript; these cover the steps around it. Hand off rather than182re-implement:183184| Skill | What it covers |185|---|---|186| `nature-writing` | Drafting the manuscript and its section-level argument (input to this one) |187| `nature-polishing` | Language polishing and academic phrasing (input to this one) |188| `nature-citation` | Searching for and exporting reference entries (RIS / ENW / Zotero RDF); export BibTeX from the reference manager for the `.bib` this skill consumes |189| `nature-ref-verifier` | Cross-checking reference metadata before submission |190| `nature-paper2ppt` | Turning the same manuscript into a presentation deck |191192Upstream engine, the general-purpose pip package, and the changelog:193[md-to-word](https://github.com/ls-open/md-to-word).