DOCX Creator

DOCX Creator

Thin incremental layer over minimax-skills:minimax-docx. Not a document engine.

Read this first. The OpenXML SDK capability lives in minimax-docx. This skill contains zero engine code. What it contains is the part that took a full debugging session to learn: where that engine's CLI stops being usable, how to drive its SDK correctly for Chinese formal documents, and how to verify the output so you don't ship a file that looks fine to you and broken in Word.

Division of labor

Locate the engine at the marketplace install path, typically ~/.claude/plugins/marketplaces/minimax-skills/skills/minimax-docx/.

Go read minimax-docx directly for anything structural this skill does not cover — images, track changes, comments, TOC, multi-section layouts, template application. Its minimax-docx/references/ folder (cjk_typography.md, openxml_element_order.md, openxml_units.md, troubleshooting.md) and its Samples/*.cs are the authority for SDK patterns. Do not reinvent them here.

Routing: which path for this document?

Rule of thumb: the CLI's --content-json understands exactly three block types (heading, paragraph, pagebreak). Bold, lists, tables, borders, footers, fonts, alignment — none of it is expressible. A Chinese contract needs all of them. See ISSUE-001.

Quick start

The generator reads markdown and writes a formatted .docx. Copy it next to your document so build artifacts stay out of the skill directory:

# 1. Stage the generator beside your markdown
mkdir -p _docxgen && cp <skill-dir>/scripts/Program.cs <skill-dir>/scripts/mmdocx-gen.csproj \
   <skill-dir>/scripts/.gitignore _docxgen/

# 2. Generate (first run restores DocumentFormat.OpenXml + Markdig, ~20s)
dotnet run --project _docxgen -- your-doc.md your-doc.docx

# 3. Structural validation via the engine's XSD validator (note the roll-forward env — ISSUE-003)
DOTNET_ROLL_FORWARD=Major dotnet run \
  --project ~/.claude/plugins/marketplaces/minimax-skills/skills/minimax-docx/scripts/dotnet/MiniMaxAIDocx.Cli \
  -- validate --input your-doc.docx

# 4. MANDATORY visual verification — never skip, never substitute qlmanage
soffice --headless --convert-to pdf --outdir /tmp/docxcheck your-doc.docx
pdftoppm -png -r 100 /tmp/docxcheck/your-doc.pdf /tmp/docxcheck/page
# then Read every /tmp/docxcheck/page-NN.png

# 5. MANDATORY if Microsoft Word.app is installed — LibreOffice cannot see ISSUE-012
open -a "Microsoft Word" your-doc.docx   # check the title bar for "兼容性模式", check every page

Full command details and troubleshooting: scripts/README.md. Full verification steps and pass/fail criteria: references/verification_protocol.md.

Hard rules (violating these means rework)

1. Alignment is layered — this is the expensive one

Never justify the whole document. Three layers, three alignments:

The rule is machine-checkable, so do not eyeball it: if the markdown paragraph's inline tree contains a LineBreakInline, left-align that paragraph; otherwise justify it. Implemented in the case ParagraphBlock p: arm of Main's block-dispatch switch, with the break detection in InlineRuns. (Line numbers are deliberately not given here — they drift every time the file grows; see scripts/README.md's function-name lookup table instead.) Full write-up: ISSUE-004.

2. Independent lists restart; continuations retain numbering

Each independent markdown list must get its own NumId plus a LevelOverride carrying StartOverrideNumberingValue = 1. Reuse one NumId across clauses and clause 3's list silently continues from 4. Implemented across the case ListBlock lb: arm and the NumberingDefinitionsPart setup — see scripts/README.md's lookup table for both. Two SDK traps come with it (wrong class name, wrong element order) — ISSUE-005, ISSUE-006. For existing Word lists, preserve intentional continuations. Resolve numId and its level before changing geometry; numId=0 disables numbering. Typed ordinals are text, not an automatic list. See ISSUE-016.

3. CJK fonts need both slots

A run must set RunFonts { Ascii, HighAnsi, EastAsia }. Setting only the Latin slots leaves Chinese characters to Word's fallback, and the document renders in whatever the reader's machine picks. Shipped defaults: Latin Times New Roman; East Asian 宋体 for body, 黑体 for headings. Chinese bold runs switch family to 黑体 — 宋体 has no true bold weight and renderer-synthesized bold smears multi-stroke characters (ISSUE-014). Sizes are OpenXML half-points — body 21 (10.5pt, the common Chinese manuscript size), H1 36 (18pt), clause heading 28 (14pt). Body paragraphs also get a 2-character first-line indent (420 twips at 10.5pt — change it in lockstep with the body size). ISSUE-007.

4. Page and table basics

A4 is 11906 × 16838 twips with 1440 twip margins; page number goes in a centered footer PAGE field. Tables need all six borders (top/bottom/left/right/insideH/insideV, in that ECMA-376 order — ISSUE-013) and a tblGrid (ISSUE-012) — set fewer borders and cells look unruled in print; omit tblGrid and the file fails strict validation even though LibreOffice hides it. Implemented in BuildTable and the SectionProperties/FooterPart setup in Main — see scripts/README.md's lookup table.