---
name: han-academic-md-to-docx
description: Convert Markdown files into structured, editable Word DOCX documents using Chinese office, research, or newly extracted formatting profiles. Use when a user asks to turn .md into Word, preserve Markdown heading hierarchy in Word styles, render Mermaid or formulas as figures, apply office/research typography, inspect a DOC/DOCX sample for reusable formatting, or add a document-format profile from a template or written specification.
---

# Han Academic Markdown to DOCX

Use Pandoc for semantic conversion and Microsoft Word for template inspection or final QA.

## Route the request

- Use the `office` profile for notices, summaries, reports, and formal administrative material.
- Use the `research` profile for proposals, protocols, manuscripts, and academic project material.
- Use an explicitly named custom profile when the user supplies one.
- If the document type is genuinely ambiguous, ask whether to use `office` or `research` before generating the final file.

Read `references/profiles.md` for exact built-in formatting, `references/markdown-contract.md` for Markdown semantics, and `references/extending-profiles.md` when adding a new format.

## Convert

1. Read the Markdown as UTF-8 without rewriting its prose.
2. Inspect headings, lists, tables, images, links, footnotes, blockquotes, fenced code, formulas, and Mermaid blocks.
3. Warn on skipped heading levels. Do not silently repair content structure unless the user authorizes it.
4. Preserve existing visible heading numbers. Do not add a second number. Add automatic numbering only when explicitly requested.
5. For the research profile, format bracketed numeric citations in body text as superscript. Keep reference-list numbers at the normal baseline.
6. For research Mermaid blocks, use `drawio-academic-skills` to create an editable `.drawio` plus SVG, then pass the SVG files to the converter in source order. Add captions such as `图1 技术路线图`.
7. For formulas, accept user-provided PNG/SVG renderings. Otherwise keep Pandoc's native editable Word equation when possible; never drop or rasterize a formula without reporting the choice.
8. Run `scripts/convert_md_to_docx.ps1` with the selected profile. Write a new `.docx`; never overwrite the Markdown source or an existing Word original.
9. Run `scripts/validate_docx.ps1` with `-CheckResearchCitations` for research output, and inspect the rendered document when the task is high stakes or visually complex.
10. Report the input, profile, output, media treatment, validation performed, and any unresolved formatting gaps.

Example:

```powershell
powershell -ExecutionPolicy Bypass -File scripts/convert_md_to_docx.ps1 `
  -InputPath "notes.md" -OutputPath "notes_research.docx" -Profile research `
  -MermaidSvg "technical-route.svg" -TableStyle grid -AddToc
```

## Add or update a format profile

1. Treat explicit written requirements as authoritative over incidental formatting in a sample file.
2. Run `scripts/inspect_word_format.ps1` against `.doc` or `.docx` samples in read-only mode.
3. Distinguish consistent styles from one-off direct formatting and document any conflicts.
4. Present the extracted rules to the user for confirmation before changing the skill.
5. Add a new JSON profile under `assets/profiles/`; do not overwrite an existing profile unless the user explicitly requests replacement.
6. Generate its reference DOCX with `scripts/build_reference_doc.ps1`, test it on representative Markdown, and validate the output.
7. Update `references/profiles.md` and `agents/openai.yaml` only when user-facing scope changes.

## Quality and safety

- Preserve Chinese text and use Times New Roman for Latin text and numbers where the profile requires it.
- Use real Word heading styles so navigation and TOC generation work.
- Keep SVG aspect ratio and fit images within the printable width.
- Keep tables within page margins; repeat header rows when feasible.
- Do not invent missing format requirements. Mark derived defaults separately from source-confirmed rules.
- Prefer local tools. Do not claim the full Codex interaction is offline merely because conversion and rendering are local.