lightest-docx

name	lightest-docx
skill_id	lightest_docx_skill
description	当用户要创建或修改磁盘上的 Word .docx（封面、图表、修订、OOXML 级排版、模板填占位）且文档未在 Word/WPS 中打开时使用；须 unzip 解析 XML 以保留版式。**触发**：.docx、Word 文档、创建 Word、改 Word 版式、track changes、模板填充（磁盘文件）。**加载**：`skills_fetch(skill_ids=["lightest_docx_skill"])` → 按任务读 SKILL.md 与 scripts。**勿用**：Word 已打开 live 编辑 → `lightest_word_live_skill`；课程论文/三线表国标 → `lightest_docx_cn_paper_skill`。

LighTest Word .docx（内置 Skill）

官方内置：连接项目时同步到 .lightest/skills/lightest-docx/；扫描器读 skill_id: lightest_docx_skill。

技能分工

技能	何时
本技能	磁盘 .docx：OOXML 创建/编辑、版式保留、修订/批注、模板填占位
lightest_word_live_skill	Word/WPS 已打开，要 live WYSIWYG
lightest_docx_cn_paper_skill	中文高校论文国标（三线表等）
lightest_writing_skill	先要 prose 结构与文风，再灌 Word

工作流（强制）

阶段	动作	路径 / 工具
0. 路由	只要纯文本 → read；要版式/模板 → 本技能；Word 已开 → word_live	下表「任务路由」
1. 环境	首次 ./scripts/docx init	.lightest/skills/lightest-docx/
2a. 新建	C# SDK：Program.cs + ./scripts/docx build	工作区 .lightest/aichat-tmp/docx-work/ → docx-output/
2b. 改已有	解压 OOXML + Python lxml（禁 python-docx/docx-js）	references/EditingGuide.md
3. 校验	./scripts/docx validate FILE 或 build 内置校验	validator/
4. 交付	输出到项目或用户指定路径	勿混 C# 创建与 Python 编辑同一文档

纪律：保留版式必须 unzip/XML；read 仅适用于纯文本场景。.doc 先 libreoffice --headless --convert-to docx。

示例：模板填占位（保留版式）

用户：已有 report.docx，替换封面与正文占位符，不动版式。

1. skills_fetch → 确认非 word_live、非国标论文 skill
2. 按 EditingGuide.md：克隆段落样式改文本，不整段重建
3. ./scripts/docx validate report.docx（若走 C# 新建链则用 docx build 内置校验）
4. 交还同路径或 docx-output/ 副本

勿：用 read 当版式来源；用 python-docx 整文档重建。

任务路由（简表）

用户要	做法
新建报告/封面/原生图表	C# + assets/templates/Example.cs / CJKExample.cs + docx build
改批注/修订/track changes	Python + references/EditingGuide.md
仅读文字（摘要/翻译）	read 即可
国标课程论文 Word	lightest_docx_cn_paper_skill

---

以下 Part 1–4 为 Goals、执行环境、质量标准与 OOXML 技术参考（正文未删减）。

Part 1: Goals

⚠️ When to Unzip vs Read

To preserve ANY formatting from the source document, MUST unzip and parse XML.

Read tool returns plain text only — fonts, colors, alignment, borders, styles are lost.

Need	Method
Text content only (summarize, analyze, translate)	Read tool is fine
Formatting info (copy styles, preserve layout, template filling)	Unzip and parse XML
Structure + comments/track changes	pandoc input.docx -t markdown
User has Word/WPS open and wants live WYSIWYG edits	lightest-word-live skill + word_document tool — not this skill

Core Principles

1. Preserve formatting — When editing existing documents, retain original formatting. Clone and modify, never recreate.

2. Correct feature implementation — Comments need multi-file sync. Track Changes need revision marks. Use the right structure.

Never use python-docx/docx-js as fallback. These libraries produce lower quality output than direct XML manipulation.

Source Principle

Template provided = Act as form-filler, not designer.

• Format is the user's decision
• Task: replace placeholders, not redesign
• Like filling a PDF form—do not redesign

No template = Act as designer. Design freely based on scenario.

For .doc (legacy format), first convert with libreoffice --headless --convert-to docx.

---

Part 2: Execution

File Structure

docx/
├── SKILL.md                      ← This file (entry point + reference)
├── references/
│   └── EditingGuide.md           → Complete Python editing tutorial (comments, track changes, 5-file sync)
├── scripts/
│   ├── docx                      → Unified entry (the only script to call)
│   ├── fix_element_order.py      → Auto-fix XML element ordering
│   ├── validate_docx.py          → Business rule validation
│   ├── generate_backgrounds.py       → Morandi style backgrounds
│   ├── generate_inkwash_backgrounds.py → Ink-wash style backgrounds
│   └── generate_chart.py         → matplotlib (only for heatmaps/3D/radar; simple charts must use native)
├── assets/
│   └── templates/
│       ├── LightestDocx.csproj       → Project file template (for creating new docs)
│       ├── Program.cs            → Program entry template
│       ├── Example.cs            → Complete example (cover+TOC+charts+back cover)
│       ├── CJKExample.cs         → CJK content patterns (quote escaping, fonts)
│       └── xml/                  → XML templates for comments infrastructure
└── validator/                    → OpenXML validator (pre-compiled binary, AI does not modify)

Creating new documents: Use C# SDK with ./scripts/docx build → See Example.cs for patterns, CJKExample.cs for CJK content Editing existing documents: Use Python + lxml → See references/EditingGuide.md for complete tutorial

⚠️ Do NOT mix these approaches. C# SDK for creation, Python for editing. Never use python-docx/docx-js.

Environment Setup

First time, execute in the SKILL directory:

cd .lightest/skills/lightest-docx/
./scripts/docx init

Fixed Path Conventions (cannot be changed):

Path	Purpose
.lightest/skills/lightest-docx/	SKILL directory, where commands are executed
.lightest/aichat-tmp/docx-work/	Working directory, edit Program.cs here
.lightest/aichat-tmp/docx-output/	Output directory, final deliverables
project root	User upload / input files location

Script Commands (./scripts/docx <cmd>):

Command	Purpose
env	Show environment status (no changes)
init	Setup dependencies + workspace
build [out]	Compile, run, validate (default: output/output.docx)
validate FILE	Validate existing docx

The script automatically handles:

• Detects dotnet/python3 (required), pandoc/playwright/matplotlib (optional)
• Installed → use directly; Not installed → auto-install; Broken → repair
• Initializes working directory, copies template files

Build Process

Must use ./scripts/docx build, do not execute dotnet build && dotnet run separately (skips validation).

Program.cs Output Path Convention (Critical)

Program.cs must get output path from command line arguments, otherwise build script cannot find the generated file:

// Correct - get output path from command line arguments
string outputFile = args.Length > 0 ? args[0] : ".lightest/aichat-tmp/docx-output/output.docx";

// Wrong - hardcoded path causes build failure
string outputFile = "my_document.docx";  // Script can't find file!

Step	Action	Notes
1. Compile	dotnet build	Provides fix suggestions on failure
2. Generate	dotnet run -- <output path>	Path passed via command line args
3. Auto-fix	fix_element_order.py	Fixes XML element ordering issues
4. OpenXML validation	validator/	Mandatory
5. Business rules	validate_docx.py	Mandatory
6. Statistics	Character + word count	Optional (requires pandoc)

Validation is mandatory: On failure, file is kept but warnings are shown. Check error messages to fix issues.

Standalone Validation

cd .lightest/skills/lightest-docx/
./scripts/docx validate .lightest/aichat-tmp/docx-output/report.docx

Content Verification (Mandatory)

pandoc is the SOURCE OF TRUTH. OpenXML validator checks structure; pandoc shows actual content.

Before delivery, verify with pandoc:

• pandoc output.docx -t plain — check text completeness
• For revisions/comments: add --track-changes=all to verify marker positions

⚠️ Critical: comments.xml exists ≠ comments visible. Count mismatch = doc_tree not saved. See references/EditingGuide.md §5.3.

---

Part 3: Quality Standards

Delivery Standard

Generic styling and mediocre aesthetics = mediocre delivery.

Deliver studio-quality Word documents with deep thought on content, functionality, and styling. Users often don't explicitly request advanced features (covers, TOC, backgrounds, back covers, footnotes, charts)—deeply understand needs and proactively extend.

Language Consistency

Document language = User conversation language (including filename, body text, headings, headers, TOC hints, chart labels, and all other text).

Headers and Footers - REQUIRED BY DEFAULT

Most documents MUST include headers and footers. The specific style (alignment, format, content) should match the document's overall design.

• Header: Typically document title, company name, or chapter name
• Footer: Typically page numbers (format flexible: "X / Y", "Page X", "— X —", etc.)
• Cover/Back cover: Use TitlePage setting to hide header/footer on first page

Professional Elements (Critical)

Create documents that exceed user expectations, proactively add professional elements, don't wait for users to ask. Delivery standard: Visual quality of a top designer in 2024.

Cover & Visual:

• Formal documents (proposals, reports, financials, bids, contracts) / creative documents (invitations, greeting cards) must have cover and back cover
• Covers must have designer-quality background images
• Body pages can optionally include backgrounds to enhance visual appeal

Structure:

• Long documents (3+ sections) add TOC, must add refresh hint after TOC

Data Presentation:

• When comparing data or showing trends, use charts instead of plain text lists
• Tables use light gray headers or three-line style, avoid Word default blue

Links & References:

• URLs must be clickable hyperlinks
• Multiple figures/tables add numbering and cross-references ("see Figure 1", "as shown in Table 2")
• Academic/legal/data analysis citation scenarios implement correct in-text click-to-jump references with corresponding footnotes/endnotes

TOC Refresh Hint

Word TOC is field code, page numbers may be inaccurate when generated. Must add gray hint text after TOC, informing users to manually refresh:

Table of Contents
─────────────────
Chapter 1 Overview .......................... 1
Chapter 2 Methods ........................... 3
...

(Hint: On first open, right-click the TOC and select "Update Field" to show correct page numbers)

Hint text requirements:

• Visually subtle — gray color, smaller font size, should not compete with actual TOC entries
• Language: Matches user conversation language

Only When User Explicitly Requests

Feature	Reason
Watermark	Changes visual state. SDK limitation: VML watermark classes don't serialize correctly; must write raw XML to header.
Document protection	Restricts editing
Mail merge fields	Requires data source

Chart Selection Strategy (Critical)

Default to native Word charts, editable, small file size, professional.

Chart Type	Method	Notes
Pie chart	Native	Example.cs → AddPieChart()
Bar chart	Native	Example.cs → AddBarChart()
Line chart	Native	Reference bar chart structure, use c:lineChart
Horizontal bar	Native	Reference bar chart structure, use barDir="bar"
Heatmap, 3D, radar	matplotlib	Word native doesn't support
Complex statistics (box plot, etc.)	matplotlib	Word native doesn't support

Native charts are preferred (editable, smaller files), but matplotlib is acceptable for data analysis scenarios.

Inserting Images/Charts

Any PNG (matplotlib charts, backgrounds, photos) must be inserted using AddInlineImage():

AddInlineImage(body, mainPart, "/path/to/image.png", "Description", docPrId++);

Critical:

• Chart labels/titles must match document language (e.g., Chinese labels for Chinese docs)
• Build output shows X images — if 0, images were not inserted

Content Constraints

Word/Page Count Requirements

User Request	Execution Standard
Specific word count (e.g., "3000 words")	Actual output within ±20%
Specific page count (e.g., "5 pages")	Exact match
Range (e.g., "2000-3000 words")	Within range
Minimum (e.g., "at least 5000 words")	No more than 2x the requirement

Forbidden: Padding word count with excessive bullet point lists. Maintain information density.

Outline Adherence

• User provides outline: Follow strictly, no additions, deletions, or reordering
• No outline provided: Use standard structure
  • Academic: Introduction → Literature → Methods → Results → Discussion → Conclusion
  • Business: Executive Summary → Analysis → Recommendations
  • Technical: Overview → Principles → Usage → Examples → FAQ

Scene Completeness

Think one step ahead of the user, complete elements the scenario needs. Examples below are not exhaustive — apply this principle to ALL document types:

• Exam paper → Name/class/ID fill areas, point allocation per question (consider total), grading section
• Contract → Signature and seal areas for both parties, date, contract number, attachment list
• Meeting minutes → Attendees, absentees, action items with owners, next meeting time

Design Philosophy

Color Scheme

Low saturation tones, avoid Word default blue and matplotlib default high saturation.

Flexibly choose color schemes based on document scenario:

Style	Palette	Suitable Scenarios
Morandi	Soft muted tones	Artistic, editorial
Earth tones	Brown, olive, natural	Environmental, organic
Nordic	Cool gray, misty blue	Minimalist, tech
Japanese Wabi-sabi	Gray, raw wood, zen	Traditional, contemplative
French elegance	Off-white, dusty pink	Luxury, feminine
Industrial	Charcoal, rust, concrete	Manufacturing, engineering
Academic	Navy, burgundy, ivory	Research, education
Ocean mist	Misty blue, sand	Marine, wellness
Forest moss	Olive, moss green	Nature, sustainability
Desert dusk	Ochre, sandy gold	Warm, regional

Color scheme must be consistent within the same document.

Layout

White space (margins, paragraph spacing), clear hierarchy (H1 > H2 > body), proper padding (text shouldn't touch borders).

Pagination Control

Word uses flow layout, not fixed pages. Control pagination with these properties:

Property	XML	Effect
Keep with next	<w:keepNext/>	Heading stays on same page as following paragraph
Keep lines together	<w:keepLines/>	Paragraph won't break across pages
Page break before	<w:pageBreakBefore/>	Force new page (for H1)
Widow/orphan control	<w:widowControl/>	Prevent single lines at top/bottom of page

// Example: H1 always starts on new page, stays with next paragraph
new ParagraphProperties(
    new ParagraphStyleId { Val = "Heading1" },
    new PageBreakBefore(),
    new KeepNext(),
    new KeepLines()
)

Table pagination:

// Allow row to break across pages (avoid large blank areas)
new TableRowProperties(
    new CantSplit { Val = false }  // false = can split
)

// Repeat header row on each page
new TableRowProperties(
    new TableHeader()
)

---

Part 4: Technical Reference

Choose your path:

Task	Stack	Reference
Create new document	C# + OpenXML SDK	4.1-4.6 + Example.cs
Edit existing document	Python + lxml	4.7 + references/EditingGuide.md

---

4.1 SDK Fundamentals

Schema Compliance (MEMORIZE THESE)

OpenXML has strict element ordering requirements. Wrong order = Word cannot open the file.

Required Styles

// Normal style must exist - all Heading styles use basedOn="Normal"
styles.Append(new Style(
    new StyleName { Val = "Normal" },
    new StyleParagraphProperties(
        new SpacingBetweenLines { After = "200", Line = "276", LineRule = LineSpacingRuleValues.Auto }
    ),
    new StyleRunProperties(
        new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" },
        new FontSize { Val = "22" },
        new FontSizeComplexScript { Val = "22" }
    )
) { Type = StyleValues.Paragraph, StyleId = "Normal", Default = true });

Element Order Rules

Most ordering issues are auto-fixed by fix_element_order.py. Key rules to remember:

Parent	Key Rule
sectPr	headerRef → footerRef must come before pgSz → pgMar
Table	Must have tblGrid between tblPr and tr (see below)

Tables Must Have tblGrid

// Correct - table must define grid
var table = new Table();
table.Append(new TableProperties(...));
table.Append(new TableGrid(           // Required!
    new GridColumn { Width = "4680" },
    new GridColumn { Width = "4680" }
));
table.Append(new TableRow(...));

// Wrong - missing tblGrid, Word cannot open
var table = new Table();
table.Append(new TableProperties(...));
table.Append(new TableRow(...));  // Adding rows directly

Table Column Width Consistency

Main cause of skewed tables: gridCol width in tblGrid doesn't match cell's tcW width.

// Correct - gridCol and tcW match exactly
table.Append(new TableGrid(
    new GridColumn { Width = "3600" },  // First column
    new GridColumn { Width = "5400" }   // Second column
));

var row = new TableRow(
    new TableCell(
        new TableCellProperties(
            new TableCellWidth { Width = "3600", Type = TableWidthUnitValues.Dxa }  // Matches gridCol!
        ),
        new Paragraph(new Run(new Text("Content")))
    ),
    new TableCell(
        new TableCellProperties(
            new TableCellWidth { Width = "5400", Type = TableWidthUnitValues.Dxa }  // Matches gridCol!
        ),
        new Paragraph(new Run(new Text("Content")))
    )
);

Rule	Reason
gridCol count = table column count	Otherwise column width calculation fails
gridCol.Width = tcW.Width	Mismatch causes skewing (checked during validation)
All rows in same column use same tcW	Maintains column width consistency

Value Limits

• paraId must be < 0x80000000 (for comment paragraph IDs)

Creation vs Editing

Task	Method	Why
Create new document	C# OpenXML SDK	Handles package structure, rels, Content_Types automatically
Edit existing document	Python + lxml	Transparent, no black box, full control

For creating new documents: Use Example.cs patterns with SDK.

For editing existing documents: See references/EditingGuide.md for complete Python workflow.

---

Example.cs

Read the entire file to understand the overall structure, not just individual functions. The file demonstrates how sections connect (cover → TOC → body → back cover).

The "Project Proposal", "[Company Name]", etc. in Example are example content only, and the color scheme is for reference only.

What to Learn	What NOT to Learn
Section division (cover → TOC → body → back cover)	Specific color values
Floating background insertion code	Business content from the example
Chart creation API calls	Copy/wording from the example
Style definition structure	Hardcoded data from the example

⚠️ Do NOT copy the Example's color scheme. Redesign visual style based on YOUR document's scenario, like a top designer.

Function Index (read source for implementation details):

Feature	Function	Line #
Document Structure
Styles (Normal, Heading1-3)	AddStyles()	85-203
Cover page	AddCoverSection()	369-453
Table of contents	AddTocSection()	458-526
Body section	AddContentSection()	531-729
Back cover	AddBackcoverSection()	734-794
Visual Elements
Floating background	CreateFloatingBackground()	228-279
Proportional inline image	AddInlineImage()	285-364
Tables
Three-line table	CreateDataTable()	853-888
Header row (gray bg)	CreateSimpleHeaderRow()	933-971
Data row	CreateSimpleDataRow()	976-1008
Charts
Pie chart	AddPieChart()	1013-1049
Bar chart	AddBarChart()	1133-1169
Page Elements
Header with background	within AddContentSection()	534-575
Footer with page numbers	within AddContentSection()	578-588
Page number field	CreatePageNumberField()	1345-1354
Total pages field	CreateTotalPagesField()	1356-1365
Advanced Features
Footnote	AddFootnote()	1370-1410
Cross-reference	CreateCrossReference()	1415-1425
Numbering/lists	CreateBasicNumbering()	1327-1340

CJKExample.cs

CJK documents must read CJKExample.cs only — reading Example.cs instead will cause errors (missing font config, quote escaping). It handles:

• Quote escaping ("" → \u201c \u201d)
• CJK font configuration (SimHei, Microsoft YaHei)
• Paragraph indentation for CJK text

Structure is identical to Example.cs — no need to read both.

4.2 Content Elements

Field Codes

PAGE/NUMPAGES/DATE/TOC — structure: FieldChar(Begin) → FieldCode(" PAGE ") → FieldChar(Separate) → Text → FieldChar(End). Results cached; WPS doesn't support UpdateFieldsOnOpen.

Bookmarks and Cross-References

Bookmarks mark positions (BookmarkStart/BookmarkEnd with matching IDs); cross-references link via REF field (" REF bookmarkName \\h ").

Pitfall: Deleting bookmarked text deletes bookmark → "Error! Reference source not found".

4.3 Visual Design

Background Image Design

Cover/back cover must have background. Background images should have center white space, use low saturation colors. Background images must NOT contain any text; text should be implemented in Word for user editability.

Design Flow

1. Read example: Read scripts/generate_backgrounds.py for HTML/CSS techniques (radial-gradient, transparency, positioning)
2. Choose direction: Select a style direction from the table below based on document scenario
3. Create original: Write new HTML/CSS from scratch—the example shows ONE style, yours should be different

⚠️ Copying the example = all documents look the same = mediocre delivery. Each document deserves a unique visual identity matching its content and purpose.

Style Reference

Style	Key Elements	Scenarios
MUJI	Thin borders + white space	Minimalist, Japanese, lifestyle
Bauhaus	Scattered geometric shapes	Art, design, creative
Swiss Style	Grid lines + accent bars	Professional, corporate
Soft Blocks	Soft color rectangles, overlapping transparent	Warm, education, healthcare
Rounded Geometry	Rounded rectangles, pill shapes	Tech, internet, youthful
Frosted Glass	Blur + transparency + subtle borders	Modern, premium, tech
Gradient Ribbons	Soft gradient ellipses + small dots	Feminine, beauty, soft
Dot Matrix	Regular dot pattern texture	Technical, data, engineering
Double Border	Nested borders + corner decorations	Traditional, formal, legal
Waves	Bottom SVG waves + gradient background	Ocean, environmental, flowing
Warm Natural	Earth tones + organic shapes	Environmental, agriculture, natural

Technical: Playwright generates 794×1123px (device_scale_factor=2), insert as floating Anchor with BehindDoc=true. See Example.cs:CreateFloatingBackground().

Letterhead (Business Documents)

For formal business letters, consider adding a letterhead in the header area. Common patterns:

• Full letterhead on first page (logo + company name + contact info), simplified or hidden on subsequent pages
• Use TitlePage in SectionProperties to enable different first-page header
• Design flexibly based on the specific business context—no fixed rules

Two-Column Layout

Use sectPr with Columns. Affects entire section until next sectPr.

4.4 Special Content

Math Formulas (OMML)

Core pattern: <m:e> is the universal content container. Almost all elements wrap content in <m:e>.

Text: Always <m:r><m:t>text</m:t></m:r>, never bare text.

Root: <m:oMath> (inline) or <m:oMathPara> (display). Do NOT nest <m:oMath> inside another.

Structure examples:

Element	Structure
Fraction	<m:f><m:num><m:e>…</m:e></m:num><m:den><m:e>…</m:e></m:den></m:f>
Subscript	<m:sSub><m:e>base</m:e><m:sub><m:e>…</m:e></m:sub></m:sSub>
Superscript	<m:sSup><m:e>base</m:e><m:sup><m:e>…</m:e></m:sup></m:sSup>
Radical	<m:rad><m:deg><m:e>n</m:e></m:deg><m:e>radicand</m:e></m:rad>
Matrix	<m:m><m:mr><m:e>cell</m:e><m:e>cell</m:e></m:mr></m:m>
Nary (∑∫)	<m:nary><m:sub><m:e>…</m:e></m:sub><m:sup><m:e>…</m:e></m:sup><m:e>body</m:e></m:nary>
Delimiter	<m:d><m:dPr><m:begChr m:val="("/><m:endChr m:val=")"/></m:dPr><m:e>…</m:e></m:d>
Equation array	<m:eqArr><m:e>eq1</m:e><m:e>eq2</m:e></m:eqArr>

Trap: Matrix uses <m:e> for cells, NOT <m:mc> (which is for column properties).

Curly Quotes in C# Strings

C# treats " " as string delimiters → CS1003. Simplest fix: Use escaped straight quotes \" in string literals. If curly quotes are required, use XML entity encoding: “ ” (doubles) or ‘ ’ (singles).

Chinese quote handling — see CJKExample.cs for complete patterns:

// ❌ Wrong - Chinese quotes break compilation
new Text("请点击"确定"按钮")  // CS1003!

// ✓ Correct - use Unicode escapes
new Text("请点击\u201c确定\u201d按钮")

Character	Unicode	Usage
" (left double)	\u201c	Opening quote
" (right double)	\u201d	Closing quote
' (left single)	\u2018	Opening single
' (right single)	\u2019	Closing single

⚠️ Do NOT use verbatim strings @"" — \u escapes don't work in verbatim strings:

// ❌ WRONG - @"" verbatim string, \u NOT escaped, outputs literal "\u201c"
string text = @"她说\u201c你好\u201d";  // Outputs: 她说\u201c你好\u201d

// ✓ CORRECT - regular string, \u IS escaped
string text = "她说\u201c你好\u201d";   // Outputs: 她说"你好"

// ✓ For long text, use + concatenation
string para = "第一段内容，" +
              "她说\u201c这是引用\u201d，" +
              "继续写第二段。";

Units

Twips = 1/20 pt (11906 = A4 width). Half-points for font size (24 = 12pt). EMU = 914400/inch.

4.5 Page Layout

Image Size

wp:extent and a:ext Cx/Cy must match. For proportional scaling: read PNG header (bytes 16-23) for dimensions, calculate cy = cx * height / width.

Pagination Control

Add KeepNext to title/chart paragraphs to prevent orphaned titles or chart-caption separation.

Section Breaks

sectPr inside pPr = last paragraph of section. Avoid PageBreak + Continuous (blank page). Use NextPage.

Table of Contents (TOC)

WPS doesn't support UpdateFieldsOnOpen → must pre-populate TOC entries using field code structure: FieldChar(Begin) → FieldCode(" TOC ...") → FieldChar(Separate) → placeholder entries (hyperlinked text + page numbers) → FieldChar(End). The placeholder entries between Separate and End allow Word to display a TOC immediately; users refresh to get accurate page numbers. Never use static text paragraphs to simulate a TOC—must use field code structure, otherwise it cannot be refreshed. See Example.cs:AddTocSection().

Parameters: \o "1-3" (heading levels), \h (hyperlinks), \z (hide page# in web), \u (outline level).

Headings must use built-in Heading1/Heading2 styles (custom styles not recognized).

Alignment and Typography

CJK body: justify + 2-char indent. English: left. Table numbers: right. Headings: no indent.

4.6 Page Elements

Headers and Footers

// 1. Create header part
var headerPart = mainPart.AddNewPart<HeaderPart>();
var headerId = mainPart.GetIdOfPart(headerPart);

headerPart.Header = new Header(
    new Paragraph(
        new ParagraphProperties(
            new ParagraphStyleId { Val = "Header" },
            new Justification { Val = JustificationValues.Center }
        ),
        new Run(new Text("Document Title"))
    )
);

// 2. Create footer part (with page numbers)
var footerPart = mainPart.AddNewPart<FooterPart>();
var footerId = mainPart.GetIdOfPart(footerPart);

var footerPara = new Paragraph(
    new ParagraphProperties(
        new Justification { Val = JustificationValues.Center }
    )
);
// PAGE field: Begin → FieldCode → Separate → Text → End
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }));
footerPara.Append(new Run(new FieldCode(" PAGE ")));
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }));
footerPara.Append(new Run(new Text("1")));  // Placeholder, updated on open
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.End }));
footerPara.Append(new Run(new Text(" / ") { Space = SpaceProcessingModeValues.Preserve }));
// NUMPAGES field (same structure)
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }));
footerPara.Append(new Run(new FieldCode(" NUMPAGES ")));
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }));
footerPara.Append(new Run(new Text("1")));
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.End }));
footerPart.Footer = new Footer(footerPara);

// 3. Reference in SectionProperties
new SectionProperties(
    new HeaderReference { Type = HeaderFooterValues.Default, Id = headerId },
    new FooterReference { Type = HeaderFooterValues.Default, Id = footerId },
    new PageSize { Width = 11906, Height = 16838 },
    new PageMargin { Top = 1440, Right = 1440, Bottom = 1440, Left = 1440, Header = 720, Footer = 720 }
)

Header/Footer Types:

Type	HeaderFooterValues	Purpose
Default	.Default	Odd pages (or all pages)
Even	.Even	Even pages
First	.First	First page

Different first page (for cover): add TitlePage() to sectPr.

Different odd/even pages: add <w:evenAndOddHeaders/> in settings.xml.

Footnotes and Endnotes

Separator trap: FootnotesPart/EndnotesPart must include Id=-1 (Separator) and Id=0 (ContinuationSeparator) before any user notes. Missing these → Word fails to render.

<!-- Required in footnotes.xml / endnotes.xml before user notes -->
<w:footnote w:type="separator" w:id="-1">
  <w:p><w:r><w:separator/></w:r></w:p>
</w:footnote>
<w:footnote w:type="continuationSeparator" w:id="0">
  <w:p><w:r><w:continuationSeparator/></w:r></w:p>
</w:footnote>
<!-- User notes start from id="1" -->

Lists

Requires NumberingDefinitionsPart with AbstractNum + NumberingInstance. Apply via NumberingProperties in paragraph.

Multi-level: create AbstractNum with multiple Levels. Formats: Decimal, UpperLetter, LowerRoman, Bullet, ChineseCounting.

Hyperlinks

Must use <w:hyperlink> element, not plain text. Requires relationship first:

var relId = mainPart.AddHyperlinkRelationship(new Uri("https://example.com"), true).Id;
paragraph.Append(new Hyperlink(new Run(
    new RunProperties(new Color { Val = "0563C1" }, new Underline { Val = UnderlineValues.Single }),
    new Text("Click here")
)) { Id = relId })

Charts and Visualization

Requirement	Preferred	Alternative
Data charts	Word native	matplotlib PNG
Flowcharts	DrawingML Shapes	Table layout
Illustrations	Image generation	Image search

Word Chart: Use NumberLiteral (no Excel), DataPoint for colors. See Example.

matplotlib: dpi=300, axes.unicode_minus=False. Font/labels must match document language.

4.7 Editing Operations (Python API)

Use docx_lib.editing for comments and track changes:

from scripts.docx_lib.editing import (
    DocxContext,
    add_comment, reply_comment, resolve_comment, delete_comment,
    insert_paragraph, insert_text, propose_deletion,
    reject_insertion, restore_deletion, enable_track_changes
)

with DocxContext("input.docx", "output.docx") as ctx:
    # add_comment(ctx, para_text, comment, highlight=None)
    # - para_text: text to locate paragraph
    # - comment: comment content
    # - highlight: text to highlight (omit to highlight entire paragraph)
    add_comment(ctx, "M-SVI index", "Please define", highlight="M-SVI")
    insert_text(ctx, "The method", after="method", new_text=" and materials")

Complete guide: references/EditingGuide.md

4.8 XML Quick Reference

Text Formatting (rPr)

<w:r>
  <w:rPr>
    <w:rFonts w:ascii="Times New Roman" w:eastAsia="SimSun"/>
    <w:sz w:val="24"/>  <!-- 12pt = 24 half-points -->
    <w:b/><w:i/><w:u w:val="single"/>
    <w:color w:val="FF0000"/>
  </w:rPr>
  <w:t>text</w:t>
</w:r>

Font sizes: 21=10.5pt, 24=12pt, 28=14pt, 32=16pt, 44=22pt

Track Changes Structure

<!-- Insertion: <w:ins> wraps <w:r> -->
<w:ins w:id="1" w:author="..." w:date="...">
  <w:r><w:rPr>...</w:rPr><w:t>text</w:t></w:r>
</w:ins>

<!-- Deletion: <w:del> wraps <w:r> (same pattern as ins!) -->
<w:del w:id="2" w:author="..." w:date="...">
  <w:r><w:rPr>...</w:rPr><w:delText>text</w:delText></w:r>
</w:del>

Key: Both <w:ins> and <w:del> wrap <w:r>, not inside it. Use <w:delText> instead of <w:t> for deletions.

Schema Constraints

Rule	Requirement
RSID values	8-digit uppercase hex: 00A1B2C3
Whitespace	xml:space="preserve" for leading/trailing spaces
Revision structure	<w:ins>/<w:del> wrap <w:r>, must have w:id attribute

---

Complete examples: See references/EditingGuide.md for full working code.