Markdown To DOCX

Skill: Markdown to DOCX

Use this skill when the user wants .md files exported to .docx with pandoc.

What this skill does

• Converts one Markdown file or all top-level Markdown files in a directory.
• Creates one .docx per source .md.
• Preserves images by setting a broad --resource-path.
• Normalizes Obsidian image embeds like ![[image.png]] and ![[image.png|697]] before conversion.
• Repairs the common case where a figure caption and an Obsidian image were accidentally merged onto one line.
• Can render Markdown against a Word .dotx/.docx reference template and apply post-processing for polished Word output.
• Renders Mermaid code blocks to PNG images when Node.js and npx are available.

Workflow

1. Confirm pandoc is installed with pandoc --version.
2. Inspect the source folder for Markdown files and image syntax if needed.
3. Run the bundled script from this skill folder:

SKILL_DIR="/path/to/markdown-to-docx"
"$SKILL_DIR/scripts/convert_markdown_to_docx.sh" \
  "<source-path>" \
  "<output-dir>" \
  "[resource-root]"

Parameters

• source-path: a single .md file or a directory that contains .md files.
• output-dir: destination directory for generated .docx files.
• resource-root (optional): root directory that contains shared assets such as resources/. If omitted, the script infers likely roots from the source location.

Template Workflow

When the user provides a Word template:

Step 1: Convert (auto-fixes captions)

The conversion script automatically inserts missing table/figure captions into the normalized markdown before calling pandoc. No manual pre-check is needed — the pipeline:

1. Normalizes Obsidian embeds and markdown syntax
2. Runs validate_captions.py fix to auto-insert any missing 表N-M / 图N-M captions (derived from table headers or surrounding context)
3. Converts with pandoc + Lua style filter
4. Post-processes the docx (fonts, styles, tables, borders, headers)

You can still run a manual pre-check to preview what will be fixed:

SKILL_DIR="/path/to/markdown-to-docx"
python3 "$SKILL_DIR/scripts/validate_captions.py" \
  pre "<source-md>"

SKILL_DIR="/path/to/markdown-to-docx"
"$SKILL_DIR/scripts/render_markdown_with_dotx.sh" \
  "<source-md>" \
  "<output-docx>" \
  "<template-dotx-or-docx>" \
  "[book-title]" \
  "[resource-root]" \
  "[shortcut-template]"

This script automatically:

• Auto-inserts missing 表N-M / 图N-M captions (derived from table headers or surrounding context)
• Maps image blocks, figure/table captions to publisher paragraph styles via Lua filter
• Post-processes for code style, fonts (Times New Roman + 宋体), table borders, layout
• Rewrites unordered-list indentation so bullet text aligns with Chinese paragraph first-line indent instead of Word's default deep indent
• Rewrites ordered and unordered lists so the marker column aligns with the Chinese body paragraph's two-character first-line indent instead of drifting too far left
• Applies Word keep with next to image paragraphs and table captions so images stay with figure captions and captions stay with tables
• Removes the code-block first-line indent from the exported Source Code paragraph style
• Clears first-line indent inside every table cell paragraph so table content does not inherit body-text indentation
• Replaces header text with chapter title
• Suppresses template auto-numbering when headings already contain explicit chapter numbers
• Extracts figure explanations and shortens captions for editor style
• Optionally injects Word shortcut bindings from the original .dotx template
• Automatically preserves Word shortcut bindings when the provided template already contains word/customizations.xml

Step 2: Post-check — validate generated docx

SKILL_DIR="/path/to/markdown-to-docx"
python3 "$SKILL_DIR/scripts/validate_captions.py" \
  post "<output-docx>"

This checks:

1. No Compact style paragraphs (undefined style)
2. No VML horizontal rules (o:hr="t")
3. Font defaults = Times New Roman + 宋体 (not Calibri)
4. First-line indent present in Normal style
5. All tables have borders (tblBorders or tcBorders)
6. Image paragraphs (图) and table captions (表题1-1) have keep with next
7. Code block style has no first-line indent
8. Ordered and unordered list geometry keeps the marker column aligned with Chinese paragraph first-line indent
9. Table cell paragraphs explicitly clear first-line indent
10. Table captions (表X-Y) present and sequentially numbered
11. Figure captions (图X-Y) present and sequentially numbered

If post-check reports ERRORs, investigate and fix. The most common post-check error is missing captions — which means the markdown source was missing them (go back to Step 1).

Current editorial rules are tracked in:

• references/editorial-template-rules.md

Notes

• The script only converts top-level .md files when a directory is passed.
• Source Markdown files are not modified. Normalization happens in a temporary directory.
• If the user wants recursive conversion, patch the script first instead of reimplementing the workflow ad hoc.
• If the publisher template contains word/customizations.xml, the render script now auto-injects those keymap customizations into the generated .docx. You can still pass an explicit shortcut-template when the shortcut source differs from the reference template.
• MANDATORY: Always run post-check after conversion. Never skip validation. Caption auto-fix runs automatically during conversion.