Pandoc Chinese Word Template Skill
Bundled Chinese Word reference templates and Lua filters make Pandoc export Markdown to docx that actually follows Chinese typographic conventions.
Local document conversion with no network calls, credential access, or destructive operations in scope; workflow is transparent and prompts output verification. Deducted because the referenced scripts (scripts/md2docx.py etc.) are not present in the provided evidence, so least-privilege behavior cannot be statically verified; license metadata unknown; no declared rollback or confirmation mechanism.
SKILL.md gives clear command paths, a template selection table, a PowerShell fallback when Bash is unavailable, and post-conversion validation steps — good self-consistency. Deducted for missing script source in evidence, unverified error handling and failure feedback, and no tests or edge cases; static review cannot exceed 10.
Clear scenario (Markdown↔DOCX with Chinese typography), precise semantic triggers, and explicit non-fit boundaries (WPS, macOS Word). Strong fit for Chinese users and note apps (SiYuan, Typora, Obsidian). Deducted because prerequisite environment details (Pandoc/Python installation) are thin in SKILL.md itself.
Well-layered docs: concise SKILL.md, detailed README with FAQ and known limitations, active changelog through 2026-05. Deducted for missing license in evidence, no declared versioning of scripts/Lua filters, and potential cross-platform issues with Chinese template filenames.
Clear goal and evident comparative value (fixing Pandoc's default DOCX styling for Chinese documents), with before/after screenshots and in-depth guidance. Deducted because static review cannot execute or reproduce representative outputs; claims rest on author-provided screenshots, so capped below the executed ceiling of 7.
Multiple corroborating material types: changelog, comparison screenshots, Zhihu blog series, and a cross-referenced upstream pandoc issue. Deducted because all evidence is author-supplied with no third-party execution proof or test suite; key paths are not independently reproducible; coverage is limited, below the static cap of 5.
- License is unconfirmed in the evidence; verify the repository LICENSE before enterprise use.
- The Python scripts referenced by SKILL.md were not provided in the reviewed evidence; manually inspect them before installation.
- Templates are tested only on Windows Microsoft Word; WPS and macOS Word may render differently.
- Effectiveness claims rest on author screenshots and blogs, not independent execution; do a small-sample conversion check before important deliveries.
- Requires local Pandoc and Python; Chinese template filenames may cause path encoding issues on non-Windows environments.
What does this skill do, and when should you use it?
Pandoc's default Word export rarely matches Chinese typesetting expectations, and it mishandles HTML tags, image captions, and font colors. This repository ships a set of Word reference templates the author uses daily — heading numbering variants, list indentation variants, and SCI paper layouts — plus targeted Lua filters and two Python conversion scripts. A SKILL.md is included so agents like Claude Code and Codex can invoke it as a Skill. Note the templates have only been tested with Windows Office Word.
Reads Markdown or docx files and runs Pandoc for two-way conversion: md2docx.py converts Markdown to HTML first, then to docx (with the markdown-to-docx.lua aggregate filter), while docx2md.py converts docx to GitHub Flavored Markdown with optional media extraction. Exports apply a reference template from templates/, controlling body fonts (SimSun / Times New Roman), bold SimHei headings, multilevel heading numbering, list indents, blockquote and code-block borders. Separate Lua filters handle HTML tag recognition (sub/sup/img), converting image title text into numbered Figure captions, preserving font colors from HTML spans, and giving inline code its own Word style.
- SiYuan note users who want Chinese-compliant Word exports configure --reference-doc in Settings → Export → Pandoc arguments
- Typora users point to the template in Preferences → Export → Word (.docx) so daily notes export pre-styled
- Obsidian users install the obsidian-enhancing-export plugin and add --reference-doc as a custom argument in the Word command template
- Researchers exporting Markdown papers as SCI-style docx with double spacing, numbered headings, line numbers, and Figure captions
- Agent users in Claude Code or Codex asking to 'convert Markdown to Word' or 'export docx with the Chinese template' trigger the skill automatically
- Users needing to convert existing Word documents back to Markdown while extracting embedded images via docx2md.py or pandoc gfm
What are this skill's strengths and limitations?
- Seven ready-made Chinese-typesetting Word templates covering heading numbering on/off, flush-left vs indented wrapped list lines, no first-line indent, and SCI paper layouts (double spacing plus line numbers)
- Five targeted Lua filters fix real Pandoc pain points: dropped HTML tags, captions using alt instead of title text, lost font colors, image caption numbering, and inline-code styling
- Both scripted wrappers and raw Pandoc commands are provided, with PowerShell equivalents when Bash is unavailable
- README explains in detail how to customize template styles (body, headings, multilevel list numbering, tables, lists), with the author's Zhihu posts linked
- Covers both directions: Markdown to docx and docx to Markdown, including media extraction
- Tested only with Windows Office Word; the author explicitly warns WPS and macOS Word may have compatibility issues
- Repository license is unknown — verify terms before adopting
- The ordered/unordered list bullet styles were reportedly achieved by trial and error and the author cannot reproduce them; editing based on the existing templates is recommended
- Table cell auto-centering depends on the Markdown source table using centering syntax; the template cannot force it
- Using an exported docx as a new template creates -Tok-suffixed highlight styles that cannot be changed (known Pandoc issue #10896) — use this repo's templates directly
- No test suite or version compatibility matrix is documented in the README
How do you install this skill?
Option 1: in a Skill-capable agent (Claude Code, Codex, OpenClaw), just say: 'Help me install this skill: https://github.com/Achuan-2/pandoc_docx_template'. Option 2 (manual): for Codex, create the folder %USERPROFILE%\.codex\skills\pandoc-docx-template; for Claude Code, create %USERPROFILE%\.claude\skills\pandoc-docx-template, and place the Skill files from the repo inside. No automated installer is provided.
How do you use this skill?
Prerequisite: install Pandoc (verify with pandoc --version). Markdown to Word: python scripts/md2docx.py input.md -o output.docx, optionally with --reference to pick a template (default: template_标题不编号-列表第二行顶格.docx) and extra Pandoc flags after -- (e.g. -- --highlight-style tango). Word to Markdown: python scripts/docx2md.py input.docx -o output.md --media-dir assets. If Bash is unavailable, run the Pandoc pipeline directly: pandoc input.md -t html | pandoc -f html -o output.docx --reference-doc <template> --lua-filter markdown-to-docx.lua. In note apps, add the --reference-doc argument in the app's export settings.
How does this skill compare with similar options?
The author positions this as a fix for Pandoc's default docx export not matching Chinese typesetting conventions; compared with hand-rolling your own --reference-doc, the repo provides ready-made templates and an aggregate Lua filter set, removing the trial-and-error cost the author notes is common since few people share concrete template-making details.