kai-docx-generator#

Generate professional .docx documents from Markdown, or fill data into .docx templates.

Core Principles#

1. Zero Fabrication — Never invent content. If data is missing, use placeholder text ( [待填写]) or ask the user.
2. Template Filling is XML-level — {{variable_name}} patterns are matched at the w:t XML node level inside the .docx. Values are sanitized to escape & < > " ' and remove control characters.
3. Security: Path Validation — Image paths must be relative or within the current working directory. Absolute paths (e.g. /tmp/...) and path traversal ( ..) are rejected.
4. Auto-Truncation — Exceeding input limits (200KB, 20 images, 50 table rows, 20 table columns) triggers automatic truncation without error.
5. Template Strictness — --strict mode on fill_template.py returns exit code 1 when any placeholder remains unreplaced, enabling CI/CD gate usage.

Commands#

CommandWhat it doespython3 <skill-path>/scripts/generate.py <input.md> <output.docx>Convert Markdown to .docxpython3 <skill-path>/scripts/generate.py --style <style> <input.md> <output.docx>Convert with a specific style`python3 /scripts/fill_template.py --data <data.jsonfrontmatter.md> --output <out.docx> <template.docx>`python3 <skill-path>/scripts/fill_template.py --strict --data <data.json> --output <out.docx> <template.docx>Fill template, fail if placeholders remainpython3 <skill-path>/scripts/validate.py <file.docx>Validate .docx file structure

Markdown → .docx#

bash

python3 <skill-path>/scripts/generate.py input.md output.docx
python3 <skill-path>/scripts/generate.py --style report input.md output.docx

Content-Type → Style Routing#

When no --style is specified, recommend a style based on topic keywords:

Topic keywordsRecommended styleUse case合同、协议、条款、contract, agreementcontractContracts & legal documents报告、分析、数据、KPI、report, analysis, dashboardreportBusiness reports (blue headers)会议纪要、meeting minutes, 讨论meetingMeeting minutes (compact layout)红头文件、通知、通报、dispatch, official noticedispatchOfficial dispatchs (red header)技术、API、架构、代码、spec, architecturetech_specTechnical specs (monospace body)公函、商务信、letterbusiness_letterBusiness letters公告、公告通知、notice, announcementnoticeOfficial notices (large bold text)其他 / generalstandardGeneral documents

When routing, announce: "推荐使用 [style] 样式 ([description])，可用 --style 覆盖。"

Default Output Filename#

If the user does not specify an output filename, derive it from the input file:

• <input>.md → <input>.docx (same basename, replace extension)
• For generated content (no input file), use: doc-<YYYY-MM-DD>-<slug>.docx
• Slug rule: lowercase the title/topic, replace spaces and non-ASCII with hyphens, keep only alphanumeric ASCII and hyphens, max 30 chars.

Supported Markdown Features#

FeatureSyntaxHeadings (H1-H3)#, ##, ###ParagraphsText blocksBold / Italic**bold**, *italic*Bullet / Numbered lists-, 1.TablesStandard GFM tablesCode blocksTriple backticks, with optional languageBlockquotes (callout)> text → info boxImages![caption](path)Page break<!-- pagebreak -->Horizontal rule---YAML front matter---\ntitle: ...\n---

Style Presets#

StyleUse casestandard (default)General documentscontractContracts & agreements (formal, 12pt)reportBusiness reports (blue headers, 10.5pt)meetingMeeting minutes (compact, 10.5pt)business_letterBusiness letters (traditional format)tech_specTechnical specifications (monospace, dark theme)dispatchOfficial dispatchs / 红头文件 (red header)noticeOfficial notices (bold, 14pt)

YAML Front Matter#

yaml

---
title: Document Title          # 写入 docx core_properties.title
author: Author Name            # 写入 docx core_properties.author
date: 2026-04-10               # 写入 docx core_properties.created
lang: zh                       # 可选: zh | en, 影响默认文本
header:
  text: CONFIDENTIAL           # 页眉文字
  alignment: center            # left | center | right
footer:
  page_number: true            # 显示页码
toc:
  max_level: 3                 # TOC 包含的最大标题级别 (1-3)
---

All fields are optional. title, author, and date are written to the .docx core properties (visible in Word → File → Info).

Template Filling#

bash

# With JSON data
python3 <skill-path>/scripts/fill_template.py --data data.json --output output.docx template.docx

# With Markdown front matter as data
python3 <skill-path>/scripts/fill_template.py --data frontmatter.md --output output.docx template.docx

# Strict mode: fail if any placeholder remains unreplaced
python3 <skill-path>/scripts/fill_template.py --strict --data data.json --output output.docx template.docx

Data format (JSON):

json

{
  "company_name": "Acme Corp",
  "amount": "¥1,000,000",
  "date": "2026-04-10"
}

Template placeholders are {{variable_name}} patterns in the .docx text (matched at w:t XML node level). Values are automatically sanitized to escape XML special characters and remove control characters. Long values are truncated to prevent layout breakage.

--strict Mode#

When --strict is passed, the script exits with code 1 if any {{placeholder}} remains unreplaced after filling. This enables CI/CD gating: all placeholders must have corresponding data keys.

Input Limits#

• Markdown size: 200KB max
• Images: 20 max
• Table rows: 50 max
• Table columns: 20 max

Exceeding limits triggers automatic truncation with no error.

QA Process#

After generating a .docx, run these checks:

Automated checks (run validate.py on the output):

1. File is valid ZIP with required structure ( word/document.xml, [Content_Types].xml, word/_rels/document.xml.rels)
2. XML is parseable (no malformed tags)
3. File size is reasonable (> 50KB warning, > 50MB warning)
4. No unreplaced {{placeholders}} detected

Visual checks (open in Word/WPS): 5. Style conformance — headings use the correct style preset colors and fonts (see references/style-presets.md for exact values) 6. Spacing — callouts have proper spacing from surrounding elements 7. Tables — column widths are reasonable, no emoji overlap 8. Code blocks — monospace font + gray background rendering 9. TOC — if requested, TOC field code is present (requires Word to update fields) 10. Images — embedded images render at correct size, no broken links

Template filling checks: 11. All {{placeholders}} with matching data keys are replaced 12. No XML corruption — the output opens without error 13. Long values are truncated appropriately (no layout breakage)

Use --validate flag with generate.py to run automated checks automatically after generation.

Works with#

• kai-report-creator — generate .docx reports from markdown output
• Any Markdown content (reports, specs, meeting notes, contracts)
• Existing .docx templates with {{placeholder}} variables