nature-paper2word

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: ![](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. This reads known style definitions; reference papers using custom styles or direct formatting need the paragraph-sample workflow in reference-layout.
4. 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.