RempleXI/word-docx-writer

Generate and format Word (.docx) documents from a simple markup file. Generic for Chinese long documents — lab/experiment reports, course-design reports, theses, project summaries, manuals, research reports, etc. No specific major or domain.

中文版见 README.md

What it is

word-docx-writer turns a small Markdown-like markup file into a properly formatted .docx, and can also re-style an existing .docx in one command.

Default typography (all overridable from the CLI):

Role	Word built-in style	Chinese size	pt	Paragraph format
Body	正文 / Normal	小四	12	first-line indent 2 chars, justified, 1.5 line spacing, 0 before/after
Heading 1	标题 1	三号	16	0 before/after, 1.5 line spacing, left
Heading 2	标题 2	四号	14	same as Heading 1
Heading 3	标题 3	小四	12	same as Heading 1
Figure/table caption	正文 + 黑体	小五	9	SimHei, not bold, centered, single spacing

• Fonts: Chinese SimSun (宋体), Western Times New Roman; headings stay SimSun; default color black.
• Tables: 10.5 pt, no shading, no first-line indent.
• Captions: auto-numbered per chapter (表1.1 ... / 图1.1 ...), table caption above the table, figure caption below the figure.
• Headings use real Word built-in styles so the Table of Contents (TOC field) works.

Features

• Standard library only for OOXML generation (Pillow needed only when inserting images).
• Two backends: OOXML (cross-platform, no Word required) and Word COM (Windows + Office: .doc conversion, TOC refresh).
• Template support: keep the template's cover/scoring sheet/TOC/headers, replace only the body.
• Re-style existing documents: apply fonts, sizes, paragraph formats and colors to any .docx.
• Multi-agent ready: ships SKILL.md, AGENTS.md, CLAUDE.md, GEMINI.md, Copilot and Cursor entry files.

Repository layout

word-docx-writer/
├── SKILL.md                    # DSH / Claude Skill entry
├── AGENTS.md / AGENTS_EN.md    # generic agent instructions
├── CLAUDE.md / GEMINI.md       # Claude Code / Gemini CLI entries
├── README.md / README_EN.md
├── LICENSE / CHANGELOG.md
├── scripts/
│   ├── word_style.py           # single source of truth for formatting
│   ├── build_docx.py           # markup -> .docx
│   └── read_docx.py            # read / convert .doc, .docx
├── references/
│   ├── style-spec.md           # formatting cheatsheet
│   └── markup.md               # markup syntax
├── assets/blank.docx           # bundled blank template
├── examples/                   # runnable example
├── skills/word-docx-writer.md  # bundled skill for the DSH plugin build
├── src/index.js                # minimal DSH plugin entry (skills-only bundle)
└── package.json / cordis.patch.yml

Install

1. As a DSH / Claude Skill

git clone https://github.com/RempleXI/word-docx-writer ~/.dsh/skills/word-docx-writer       # DeepSeek Harness
git clone https://github.com/RempleXI/word-docx-writer ~/.claude/skills/word-docx-writer    # Claude Code

Project-local:

git clone https://github.com/RempleXI/word-docx-writer <your-project>/.dsh/skills/word-docx-writer

2. From the zip

Download word-docx-writer-v1.0.0.zip and unzip it into any skill directory above.

3. Other agent tools

Codex / OpenCode read AGENTS.md (and AGENTS_EN.md); Gemini CLI reads GEMINI.md; Claude Code reads CLAUDE.md; GitHub Copilot reads .github/copilot-instructions.md; Cursor reads .cursor/rules/word-docx-writer.mdc.

4. As a DSH plugin (npm)

This repository can also be installed as a DSH plugin:

npm publish --access public          # publishes dsh-plugin-word-docx-writer
dsh plugin --profile web add dsh-plugin-word-docx-writer@latest

The plugin is a skills-only bundle: src/index.js is a no-op plugin entry, and the skill is bundled at skills/word-docx-writer.md.

Quick start

1. Write content.txt (see references/markup.md):

TITLE|Lab Report Title
H1|1. Objective
H2|1.1 Background
P|Body text: 2-char first-line indent, justified, 1.5 line spacing.
TCAP|Experiment data
TBL|No.;;Item;;Result
ROW|1;;Sample item;;Sample result
FCAP|Experiment setup
IMG|fig.png|12

2. Generate:

python scripts/build_docx.py --content content.txt --out report.docx

3. Re-style an existing document:

python scripts/word_style.py report.docx            # COM first, OOXML fallback
python scripts/word_style.py report.docx --method ooxml

4. Inspect structure:

python scripts/read_docx.py report.docx

Dependencies & platform

Capability	Requirement
Generation / styling (OOXML)	Python 3.8+; Pillow only for images
.doc conversion	Windows + Microsoft Word (COM)
TOC / page-number refresh	Windows + Microsoft Word (COM), or press F9 manually
Fonts	SimSun (宋体), SimHei (黑体), Times New Roman installed

pip install pywin32 Pillow

On non-Windows platforms build_docx.py and word_style.py --method ooxml work fully; .doc conversion and TOC refresh must be done with Word or LibreOffice.

CLI options (build_docx.py)

Option	Default	Description
--content	required	markup file
--out	required	output .docx
--template	assets/blank.docx	template .docx / .doc
--font / --font-ascii	宋体 / Times New Roman	East-Asian / Latin font
--body --h1 --h2 --h3	12 / 16 / 14 / 12	font sizes (pt)
--table-size	10.5	table font size
--caption-font --caption-size	黑体 / 9	caption font / size
--color	000000	default text color
--title	—	cover title (when the template has a placeholder)
--no-update-toc	—	skip the Word COM TOC refresh

License

MIT. Please keep the copyright notice.

Contributing

Issues and PRs are welcome. Please run the examples/ case before submitting.