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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
![Python](https://img.shields.io/badge/Python-3.8%2B-blue.svg)

> 中文版见 [README.md](./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

```bash
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:

```bash
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:

```bash
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`](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:

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

3) Re-style an existing document:

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

4) Inspect structure:

```bash
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 |

```bash
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](./LICENSE). Please keep the copyright notice.

## Contributing

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