Professional DOCX document creation, editing, and formatting using OpenXML SDK (.NET). Three pipelines: (A) create new documents from scratch, (B) fill/edit content in existing documents, (C) apply template formatting with XSD validation gate-check. MUST use this skill whenever the user wants to produce, modify, or format a Word document — including when they say "write a report", "draft a proposal", "make a contract", "fill in this form", "reformat to match this template", or any task whose final output is a .docx file. Even if the user doesn't mention "docx" explicitly, if the task implies a printable/formal document, use this skill.
Professional DOCX document creation, editing, and formatting using OpenXML SDK (.NET). Three pipelines: (A) create new documents from scratch, (B) fill/edit content in existing documents, (C) apply template formatting with XSD validation gate-check. MUST use this skill whenever the user wants to produce, modify, or format a Word document — including when they say "write a report", "draft a proposal", "make a contract", "fill in this form", "reformat to match this template", or any task whose final output is a .docx file. Even if the user doesn't mention "docx" explicitly, if the task implies a printable/formal document, use this skill.
license
MIT
metadata
{"author":"MiniMaxAI","category":"document-processing","sources":["ECMA-376 Office Open XML File Formats","GB/T 9704-2012 Layout Standard for Official Documents","IEEE / ACM / APA / MLA / Chicago / Turabian Style Guides","Springer LNCS / Nature / HBR Document Templates"],"version":"1.0.0"}
Create, edit, and format DOCX documents via CLI tools or direct C# scripts built on OpenXML SDK (.NET).
Setup
First time:bash scripts/setup.sh (or powershell scripts/setup.ps1 on Windows, --minimal to skip optional deps).
First operation in session:scripts/env_check.sh — do not proceed if NOT READY. (Skip on subsequent operations within the same session.)
Quick Start: Direct C# Path
When the task requires structural document manipulation (custom styles, complex tables, multi-section layouts, headers/footers, TOC, images), write C# directly instead of wrestling with CLI limitations. Use this scaffold:
// File: scripts/dotnet/task.csx (or a new .cs in a Console project)// dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli -- run-script task.csx#r "nuget: DocumentFormat.OpenXml, 3.2.0"using DocumentFormat.OpenXml;
using DocumentFormat.OpenXml.Packaging;
using DocumentFormat.OpenXml.Wordprocessing;
usingvar doc = WordprocessingDocument.Create("output.docx", WordprocessingDocumentType.Document);
var mainPart = doc.AddMainDocumentPart();
mainPart.Document = new Document(new Body());
// --- Your logic here ---// Read the relevant Samples/*.cs file FIRST for tested patterns.// See Samples/ table in References section below.
Before writing any C#, read the relevant Samples/*.cs file — they contain compilable, SDK-version-verified patterns. The Samples table in the References section below maps topics to files.
CLI shorthand
All CLI commands below use $CLI as shorthand for:
dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli --
Pipeline routing
Route by checking: does the user have an input .docx file?
User task
├─ No input file → Pipeline A: CREATE
│ signals: "write", "create", "draft", "generate", "new", "make a report/proposal/memo"
│ → Read references/scenario_a_create.md
│
└─ Has input .docx
├─ Replace/fill/modify content → Pipeline B: FILL-EDIT
│ signals: "fill in", "replace", "update", "change text", "add section", "edit"
│ → Read references/scenario_b_edit_content.md
│
└─ Reformat/apply style/template → Pipeline C: FORMAT-APPLY
signals: "reformat", "apply template", "restyle", "match this format", "套模板", "排版"
├─ Template is pure style (no content) → C-1: OVERLAY (apply styles to source)
└─ Template has structure (cover/TOC/example sections) → C-2: BASE-REPLACE
(use template as base, replace example content with user content)
→ Read references/scenario_c_apply_template.md
If the request spans multiple pipelines, run them sequentially (e.g., Create then Format-Apply).
Pre-processing
Convert .doc → .docx if needed: scripts/doc_to_docx.sh input.doc output_dir/
Preview before editing (avoids reading raw XML): scripts/docx_preview.sh document.docx
Analyze structure for editing scenarios: $CLI analyze --input document.docx
Scenario A: Create
Read references/scenario_a_create.md, references/typography_guide.md, and references/design_principles.md first. Pick an aesthetic recipe from Samples/AestheticRecipeSamples.cs that matches the document type — do not invent formatting values. For CJK, also read references/cjk_typography.md.
Gate-check is a hard requirement. Do NOT deliver until it passes. If it fails: diagnose, fix, re-run.
Also diff to verify content preservation: $CLI diff --before source.docx --after out.docx
Validation pipeline
Run after every write operation. For Scenario C the full pipeline is mandatory; for A/B it is recommended (skip only if the operation was trivially simple).
These prevent file corruption — OpenXML is strict about element ordering.
Element order (properties always first):
Parent
Order
w:p
pPr → runs
w:r
rPr → t/br/tab
w:tbl
tblPr → tblGrid → tr
w:tr
trPr → tc
w:tc
tcPr → p (min 1 <w:p/>)
w:body
block content → sectPr (LAST child)
Direct format contamination: When copying content from a source document, inline rPr (fonts, color) and pPr (borders, shading, spacing) override template styles. Always strip direct formatting — keep only pStyle reference and t text. Clean tables too (including pPr/rPr inside cells).
Track changes:<w:del> uses <w:delText>, never <w:t>. <w:ins> uses <w:t>, never <w:delText>.
Font size:w:sz = points × 2 (12pt → sz="24"). Margins/spacing in DXA (1 inch = 1440, 1cm ≈ 567).
Heading styles MUST have OutlineLevel: When defining heading styles (Heading1, ThesisH1, etc.), always include new OutlineLevel { Val = N } in StyleParagraphProperties (H1→0, H2→1, H3→2). Without this, Word sees them as plain styled text — TOC and navigation pane won't work.
Multi-template merge: When given multiple template files (font, heading, breaks), read references/scenario_c_apply_template.md section "Multi-Template Merge" FIRST. Key rules:
Merge styles from all templates into one styles.xml. Structure (sections/breaks) comes from the breaks template.
Each content paragraph must appear exactly ONCE — never duplicate when inserting section breaks.
NEVER insert empty/blank paragraphs as padding or section separators. Output paragraph count must equal input. Use section break properties (w:sectPr inside w:pPr) and style spacing (w:spacing before/after) for visual separation.
Insert oddPage section breaks before EVERY chapter heading, not just the first. Even if a chapter has dual-column content, it MUST start with oddPage; use a second continuous break after the heading for column switching.
Dual-column chapters need THREE section breaks: (1) oddPage in preceding para's pPr, (2) continuous+cols=2 in the chapter HEADING's pPr, (3) continuous+cols=1 in the last body para's pPr to revert.
Copy titlePg settings from the breaks template for EACH section. Abstract and TOC sections typically need titlePg=true.
Multi-section headers/footers: Templates with 10+ sections (e.g., Chinese thesis) have DIFFERENT headers/footers per section (Roman vs Arabic page numbers, different header text per zone). Rules:
Use C-2 Base-Replace: copy the TEMPLATE as output base, then replace body content. This preserves all sections, headers, footers, and titlePg settings automatically.
NEVER recreate headers/footers from scratch — copy template header/footer XML byte-for-byte.
NEVER add formatting (borders, alignment, font size) not present in the template header XML.
Non-cover sections MUST have header/footer XML files (at least empty header + page number footer).
See references/scenario_c_apply_template.md section "Multi-Section Header/Footer Transfer".
References
Load as needed — don't load all at once. Pick the most relevant files for the task.
The C# samples and design references below are the project's knowledge base ("encyclopedia"). When writing OpenXML code, ALWAYS read the relevant sample file first — it contains compilable, SDK-version-verified patterns that prevent common errors. When making aesthetic decisions, read the design principles and recipe files — they encode tested, harmonious parameter sets from authoritative sources (IEEE, ACM, APA, Nature, etc.), not guesses.
Font pairing, sizes, spacing, page layout, table design, color schemes
references/cjk_typography.md
CJK fonts, 字号 sizes, RunFonts mapping, GB/T 9704 公文 standard
references/cjk_university_template_guide.md
Chinese university thesis templates: numeric styleIds (1/2/3 vs Heading1), document zone structure (cover→abstract→TOC→body→references), font expectations, common mistakes
references/design_principles.md
Aesthetic foundations: 6 design principles (white space, contrast/scale, proximity, alignment, repetition, hierarchy) — teaches WHY, not just WHAT
references/design_good_bad_examples.md
Good vs Bad comparisons: 10 categories of typography mistakes with OpenXML values, ASCII mockups, and fixes
references/track_changes_guide.md
Revision marks deep dive
references/troubleshooting.md
Symptom-driven fixes: 13 common problems indexed by what you SEE (headings wrong, images missing, TOC broken, etc.) — search by symptom, find the fix
