minimax-docx

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

powershell scripts/setup.ps1

--minimal

First operation in session:

scripts/env_check.sh

NOT READY

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;

using var 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

CLI shorthand

All CLI commands below use

$CLI

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

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

references/design_principles.md

Samples/AestheticRecipeSamples.cs

references/cjk_typography.md

Choose your path:

• Simple (plain text, minimal formatting): use CLI —

  $CLI create --type report --output out.docx --config content.json

• Structural (custom styles, multi-section, TOC, images, complex tables): write C# directly. Read the relevant

  Samples/*.cs

  first.

CLI options:

--type

--title

--author

--page-size

--margins

--header

--footer

--page-numbers

--toc

--content-json

Then run the validation pipeline (below).

Scenario B: Edit / Fill

Read

references/scenario_b_edit_content.md

Choose your path:

• Simple (text replacement, placeholder fill): use CLI subcommands.
• Structural (add/reorganize sections, modify styles, manipulate tables, insert images): write C# directly. Read

  references/openxml_element_order.md

  and the relevant

  Samples/*.cs

  .

Available CLI edit subcommands:

• replace-text --find "X" --replace "Y"

• fill-placeholders --data '{"key":"value"}'

• fill-table --data table.json

• insert-section

  ,

  remove-section

  ,

  update-header-footer

$CLI edit replace-text --input in.docx --output out.docx --find "OLD" --replace "NEW"
$CLI edit fill-placeholders --input in.docx --output out.docx --data '{"name":"John"}'

Then run the validation pipeline. Also run diff to verify minimal changes:

$CLI diff --before in.docx --after out.docx

Scenario C: Apply Template

Read

references/scenario_c_apply_template.md

$CLI apply-template --input source.docx --template template.docx --output out.docx

For complex template operations (multi-template merge, per-section headers/footers, style merging), write C# directly — see Critical Rules below for required patterns.

Run the validation pipeline, then the hard gate-check:

$CLI validate --input out.docx --gate-check assets/xsd/business-rules.xsd

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).

$CLI merge-runs --input doc.docx                                    # 1. consolidate runs
$CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd     # 2. XSD structure
$CLI validate --input doc.docx --business                           # 3. business rules

If XSD fails, auto-repair and retry:

$CLI fix-order --input doc.docx
$CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd

If XSD still fails, fall back to business rules + preview:

$CLI validate --input doc.docx --business
scripts/docx_preview.sh doc.docx
# Verify: font contamination=0, table count correct, drawing count correct, sectPr count correct

Final preview:

scripts/docx_preview.sh doc.docx

Critical rules

These prevent file corruption — OpenXML is strict about element ordering.

Element order (properties always first):

w:p

pPr

w:r

rPr

t

br

tab

w:tbl

tblPr

tblGrid

tr

w:tr

trPr

tc

w:tc

tcPr

p

<w:p/>

w:body

sectPr

Direct format contamination: When copying content from a source document, inline

rPr

pPr

pStyle

t

pPr/rPr

Track changes:

<w:del>

<w:delText>

<w:t>

<w:ins>

<w:t>

<w:delText>

Font size:

w:sz

sz="24"

Heading styles MUST have OutlineLevel: When defining heading styles (Heading1, ThesisH1, etc.), always include

new OutlineLevel { Val = N }

StyleParagraphProperties

Multi-template merge: When given multiple template files (font, heading, breaks), read

references/scenario_c_apply_template.md

• 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.

Scenario guides (read first for each pipeline)

references/scenario_a_create.md

references/scenario_b_edit_content.md

references/scenario_c_apply_template.md

C# code samples (compilable, heavily commented — read when writing code)

Samples/DocumentCreationSamples.cs

Samples/StyleSystemSamples.cs

Samples/CharacterFormattingSamples.cs

Samples/ParagraphFormattingSamples.cs

Samples/TableSamples.cs

Samples/HeaderFooterSamples.cs

Samples/ImageSamples.cs

Samples/ListAndNumberingSamples.cs

Samples/FieldAndTocSamples.cs

Samples/FootnoteAndCommentSamples.cs

Samples/TrackChangesSamples.cs

Samples/AestheticRecipeSamples.cs

Note:

Samples/

scripts/dotnet/MiniMaxAIDocx.Core/

Markdown references (read when you need specifications or design rules)

references/openxml_element_order.md

references/openxml_units.md

references/openxml_encyclopedia_part1.md

references/openxml_encyclopedia_part2.md

references/openxml_encyclopedia_part3.md

references/typography_guide.md

references/cjk_typography.md

references/cjk_university_template_guide.md

references/design_principles.md

references/design_good_bad_examples.md

references/track_changes_guide.md

references/troubleshooting.md