document-format

This repository documents the skills under skills/. The primary skill, skills/word-expert-formatting, is a custom Claude Code skill that formats Chinese Word content and turns Markdown or plain text into a .docx locally — or normalizes and verifies a refreshed copy of an existing .docx.

It applies all-decimal heading numbering, and --auto-toc inserts a Word TOC field instead of static TOC text.

Quick start

Requirements:

• Python 3
• python-docx

python3 -m pip install python-docx

The script checks these at startup and exits with a clear error message if a required dependency is missing. Output documents are created from a blank Word document, so this workflow does not depend on a local template .docx file.

Reference: skills/word-expert-formatting/scripts/text_to_docx.py:3151

Run:

python3 skills/word-expert-formatting/scripts/text_to_docx.py <input-file> [output.docx] [--reserve-cover] [--auto-toc] [--with-cover|--without-cover] [--cover-text <text>] [--with-toc|--without-toc] [--style-config <path>]

If output.docx is omitted, .md / .markdown / .txt inputs still write a same-basename .docx, while .docx inputs write <stem>.refreshed.docx next to the source file.

For skill-driven runs in this repository, ask first:

1. whether to generate a cover page
2. if yes, what cover text to use (manual input; default empty)
3. whether to generate a TOC page

The skill treats those answers as explicit per-run decisions:

• generate cover + non-empty text: render the first non-empty line as the cover title and later non-empty lines as centered metadata
• generate cover + empty text: render a blank placeholder cover page
• do not generate cover: suppress automatic cover detection and placeholder insertion for that run; for an existing .docx, this also means the existing cover region is fully frozen and no cover-region formatting, section, footer, or page-number changes are allowed
• TOC generation is asked every time and then mapped to the script invocation for that run; when the existing cover region is frozen, TOC handling must stay after the detected body boundary

References:

• skills/word-expert-formatting/SKILL.md:127
• skills/word-expert-formatting/scripts/text_to_docx.py:2634

What the script does

The script currently:

• accepts .md, .markdown, .txt, and .docx
• formats headings, paragraphs, lists, tables, code blocks, footer page numbers, and simple cover sections
• renders Markdown inline emphasis (bold / italic / inline code / strikethrough), hyperlinks, task lists, blockquotes, and footnotes
• embeds local ![alt](path) images with page-fit sizing and renders mermaid fenced blocks to images (local mmdc, then draw.io CLI, then mermaid.ink, finally falls back to a code block)
• strips emoji from rendered text automatically while keeping code blocks and inline code verbatim
• uses all-decimal heading numbering
• can reserve a placeholder cover page when no cover is detected
• can generate a Word TOC field page when no explicit TOC heading is detected
• can take explicit cover / TOC decisions for a run, including manual cover text input
• loads per-level typography (font, size, color, bold, spacing, alignment) from an optional JSON config file instead of using the built-in defaults
• refreshes existing .docx files into a new output file instead of deleting and rebuilding the body
• preserves images, tables, page breaks, and section structure during existing .docx refresh
• fully freezes the existing cover region when --without-cover is chosen for an existing .docx, and only normalizes content after the detected body boundary
• still allows explicit TOC decisions during existing .docx refresh without letting TOC handling modify the frozen cover region
• uses a more formal pagination model when a cover page exists for generated output or for existing .docx runs that are not in frozen-cover mode: the cover has no page number and the body section restarts numbering from 1
• writes a .docx file

Reference: skills/word-expert-formatting/scripts/text_to_docx.py:840

Style configuration

Font, size, color, bold, line spacing, spacing before/after, first-line indent, and alignment for each of the 20 style entries (title, headings 1–9, cover title/meta/corner, body, blockquote, table, code, footer, TOC title/entry) can be overridden without touching Python code.

By default the script looks for skills/word-expert-formatting/config/style.json next to itself; if that file is absent, the built-in hardcoded defaults apply unchanged. Pass --style-config <path> to use a different file, or to require one explicitly (an explicit path that doesn't exist is an error). A config file only needs to specify the fields it wants to change — everything else is deep-merged onto the defaults:

{"styles": {"h1": {"color": "1F4E79", "size_pt": 20}}}

The shipped config/style.json mirrors the current hardcoded values exactly, and skills/word-expert-formatting/SKILL.md's "Style matrix" table is generated from it — run python3 skills/word-expert-formatting/scripts/generate_style_doc.py after editing the config to refresh that table (--check verifies it's already in sync).

Page geometry, bullet marker characters, non-typography colors, and heading-numbering/cover-detection logic are not part of this config and stay hardcoded in text_to_docx.py; the cover_title/cover_meta/cover_corner/toc_title entries also ignore the alignment field since their alignment is set explicitly in code.

References:

• skills/word-expert-formatting/config/style.json
• skills/word-expert-formatting/scripts/text_to_docx.py:3691

Skills

word-expert-formatting

Location:

• skills/word-expert-formatting/SKILL.md
• skills/word-expert-formatting/scripts/text_to_docx.py

Purpose:

• turn raw Markdown, TXT, HTML, or rough outlines into a Word-ready structured format
• apply a strict Chinese formal-document style model
• apply all-decimal heading numbering
• support local .docx generation when the input is .md, .markdown, or .txt
• support refreshed-copy normalization and verification when the input is an existing .docx

Reference: skills/word-expert-formatting/SKILL.md:1

What the skill defines

skills/word-expert-formatting/SKILL.md defines:

• supported input shapes
• heading hierarchy rules
• heading numbering behavior
• cover detection rules
• style mapping for headings, body text, tables, and footer page numbers
• output contracts for structured formatting results
• body paragraphs are normalized by clearing inherited indent, line spacing, and alignment before applying justified alignment and a 2-character first-line indent
• existing .docx refresh preserves images, tables, page breaks, and section structure instead of deleting and rebuilding the body
• existing .docx verification checks both paragraph layout and structure preservation

Reference: skills/word-expert-formatting/SKILL.md:27

Supported features

Current script support includes:

• Markdown headings (# to ######)
• paragraphs
• unordered lists
• ordered lists
• Markdown tables
• fenced code blocks
• simple cover recognition
• multi-line cover title blocks for existing .docx cover refresh
• for existing .docx cover titles, refresh only corrects font and size; it does not change existing title alignment
• placeholder cover insertion with --reserve-cover
• explicit cover generation with --with-cover and --cover-text
• explicit cover suppression with --without-cover for generated output, while existing .docx refresh keeps any cover that is already present unchanged
• explicit TOC detection (目录, TOC, Table of Contents)
• Word TOC field insertion with --auto-toc
• explicit TOC generation with --with-toc
• explicit TOC suppression with --without-toc for generated output, while existing .docx refresh keeps any TOC that is already present
• all-decimal heading numbering
• formal pagination when a cover exists: no page number on the cover, body numbering restarts from 1
• refreshed-copy normalization for existing .docx with structure preservation
• existing .docx verification for cover, TOC, body layout, tables, numbering, and structure counts
• TXT paragraph blocks
• minimal TXT heading detection for TOC generation
• per-level typography overrides via --style-config <path> or a default config/style.json, deep-merged onto built-in defaults

References:

• skills/word-expert-formatting/scripts/text_to_docx.py:695
• skills/word-expert-formatting/scripts/text_to_docx.py:822

XML debug lane

For tricky existing .docx cases where Word rendering does not match the normal refresh result, this skill also includes a local XML debug helper:

python3 skills/word-expert-formatting/scripts/debug_docx_xml.py unpack <input.docx> <output-dir>
python3 skills/word-expert-formatting/scripts/debug_docx_xml.py validate <output-dir> --original <input.docx>
python3 skills/word-expert-formatting/scripts/debug_docx_xml.py repack <output-dir> <output.docx> --original <input.docx>

This path is intended for XML-level debugging and repair, not for normal generation.

Why this skill exists alongside a generic DOCX skill

Dimension	Generic DOCX skill	word-expert-formatting
Positioning	Low-level Office/XML toolbox	End-to-end document-production workflow
Main job	Unpack, inspect, validate, repack .docx	Generate or refresh documents to this repository's formatting contract
Best at	XML surgery, schema issues, relationships, tracked changes	Cover, TOC, heading hierarchy, pagination, body and table formatting
Existing .docx handling	Good for direct XML repair	Good for refreshed-copy normalization with structure preservation
Validation focus	XML correctness	Semantic output quality + structure preservation
User cost	Higher; better for expert debugging	Lower; better for repeatable daily use
Use when	Word rendering and XML disagree, or XML needs surgical fixes	Normal formatting, refresh, and verification work

In short:

• the generic DOCX skill is the XML surgery toolkit
• word-expert-formatting is the repeatable production line for this repository's target document format
• the intended workflow is: use word-expert-formatting by default, and fall back to the XML debug lane only for hard low-level cases

Important implementation note

The skill contract and current Python script use a single heading numbering scheme:

• headings use an all-decimal hierarchy such as 1, 1.1, and 1.1.1
• this is intended for technical documents, project plans, implementation plans, and similar structured reports

Also, --auto-toc now inserts a real Word TOC field instead of static text entries. If the table of contents does not appear updated immediately in Word, use Word's update-table action after opening the document.

The newer explicit switches are intended for skill-driven runs:

• --with-cover / --without-cover override automatic cover detection for that run; on existing .docx, --without-cover only suppresses creating a new cover and does not remove or restyle one that already exists
• --cover-text implies --with-cover when used alone
• --with-toc / --without-toc override fallback TOC generation for that run; on existing .docx, --without-toc only suppresses creating a new TOC and does not remove one that already exists
• --reserve-cover and --auto-toc remain available for direct CLI compatibility

When a cover page is present or --reserve-cover / --with-cover is used, the script now creates a separate body section so the cover stays unnumbered and the body starts again at page 1.

References:

• skills/word-expert-formatting/SKILL.md:43
• skills/word-expert-formatting/scripts/text_to_docx.py:3455
• skills/word-expert-formatting/scripts/text_to_docx.py:309

Limitations

• complex embedded HTML, remote images (rendered as placeholders), and highly customized layouts are not supported yet
• mermaid fenced blocks need at least one working renderer (local mmdc, the draw.io CLI, or network access to mermaid.ink); if none are available, the block falls back to a plain code block instead of an image
• SKILL.md is a human-readable contract, not a config file the script parses — a formatting-rule change must be made in both SKILL.md and text_to_docx.py to actually affect output

Reference: skills/word-expert-formatting/SKILL.md:327

Maintenance rule

If a formatting rule change must affect generated .docx output, update both:

• skills/word-expert-formatting/SKILL.md
• skills/word-expert-formatting/scripts/text_to_docx.py

Reference: skills/word-expert-formatting/SKILL.md:165