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. This skill ships documentation only; 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 for Nature / my university"	Get a target .docx template or a written spec, then build a requirements file.
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.

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.

• 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: ![](path/img.png){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

0. Starting from nothing — md-to-word init writes a complete preset copy plus a one-page manuscript that exports as-is.
1. Built-in preset — zh-academic or en-nature. Use as-is when the user gave no detailed spec.
2. 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.
3. 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.

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

• 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.