The Lua filters are where the actual work is

The template is a style sheet pandoc already knows how to read

The starting point is that most Markdown note applications export through pandoc, and pandoc's default Word output is not something you would send to anybody. The author names the reason directly: the default styles are unattractive and do not follow Chinese typographic conventions. The fix is a pandoc feature that is barely documented in the way people need it, a custom Word template supplied at export time, and the project's whole premise is that nobody on the internet explains how to build one, mentioning only that the question comes up constantly. Building one means opening Word, defining the styles you want, and saving the file as the reference document. The repository ships several, chosen by option rather than by configuration, with variants for numbered or unnumbered headings and for a list whose second line is indented or flush to the margin, plus a template for scientific papers that sets double line spacing in the body, uses a block quote as the figure caption style, and adds line numbers. Once you have picked one, the export command is a single flag.

Tested in Windows Word, and nothing else

The first warning in the README, placed before the screenshots, is that the template is only tested in Office Word on the Windows side and may not be unsuitable for WPS or for Office on macOS. The author is explicit that it may not apply, and the reason is structural rather than accidental. A reference document is a Word file whose styles are consumed by the exporter, and two implementations of Word will not agree on every style name, every default and every font mapping, and WPS is a different application that also reads docx. The rest of the documentation is consistent with that warning rather than contradicting it, since the manual skill installation paths are written in Windows form, pointing at a directory under the user profile for Codex and another for Claude Code. So the honest summary is that this is a Windows-first artefact, and a Mac user who tries it should expect to open the file once and check. That is not a reason to skip it, because the filters are portable, but it is a reason to test before you convert a hundred documents.

The one-line export, and the two-step export when HTML is involved

Using the template from a shell is the basic case, passing the reference document path alongside an input and an output:

pandoc input.md --reference-doc templates/template_标题不编号-列表第二行顶格.docx -o output.docx

The longer command exists because of the first defect on the project's list, that pandoc does not parse HTML tags in Markdown such as sub, sup and img. The filter route solves it by running a Lua file, but the alternative is to route the document through HTML first, which is what the author uses when converting this repository's own README, because that file contains inline HTML:

pandoc README.md -t html | \
    pandoc -f html -o README.docx \
    --reference-doc templates/template_标题不编号-列表第二行顶格.docx

The pipe is the point. Markdown becomes HTML, HTML becomes docx with your template, and the intermediate representation is the only one that understands the tags pandoc drops. That is a workaround with a cost, since you have given up Markdown's own semantics for one conversion, and the Lua filter route is preferable when the filter is available, which it is, in the repository's lua directory.

Five defects, five filters, and a bundle that turns them all on

This is where the project earns its keep, and the list is specific enough to check against your own complaints. Pandoc takes the image caption from the alt text, while the author's habit, and the convention in note applications such as SiYuan and Yuque, is to use the title text instead, so lua/image-title-to-caption.lua changes the source of the caption and also applies a Figure style, which is what later lets every figure be left or right aligned in one place. Span-level font colour, written as a span element with a colour in its style attribute, is lost on export, so lua/preserve_font_color.lua keeps it. Image numbering is not customisable in the base output, so lua/image-title-to-caption-add-number.lua adds it. Code blocks and inline code both arrive under one default Source Code style, which means you cannot have a bordered block without shading and shaded inline code, so lua/add-inline-code.lua creates a separate Inline Code style you can then edit in the template. And lua/markdown-html-recognition.lua handles the HTML tags. The bundle markdown-to-docx.lua at the repository root combines them, which is how the agent skill uses it:

pandoc input.md -t html | pandoc -f html -o output.docx --reference-doc templates/template_标题不编号-列表第二行顶格.docx --lua-filter markdown-to-docx.lua

The author also notes you can select individual filters as needed rather than taking the bundle, which is the right advice since one of them changes your caption source and another may not be what you want.

A filter cannot create a style the template does not define

The interaction between the two halves is the constraint to understand before you start editing. The README says it directly when it explains how to modify the template: to change a style you must change the style of each type, not just the formatting of the paragraph you happen to be looking at. That is the difference between a style and direct formatting in Word, and it is why the inline code fix has two parts. A filter can attach a named style to a run of text, but if the reference document has no such style, there is nothing to attach, so lua/add-inline-code.lua introduces the name Inline Code and the template edit is what gives it a border, a typeface and a shading. The same logic runs the other way, which is why the caption filter applies a Figure style: the scientific paper template deliberately reuses the block quote style for figure captions, so an ordinary block quote in the same document inherits the caption appearance. That is a clever reuse and also a trap, and it is the kind of decision that only makes sense once you have edited the template by hand and seen what happens.

What the body style actually sets

The README documents the general styles in a table, and the defaults are where a Chinese-language template differs most from a Western one. Two styles are listed. The first is the body text style, applied in ordinary paragraphs, and the second is First Paragraph, which is the style of a paragraph at the start. Both default to a first-line indent, a font size of 小四, which is the Chinese name for the small-four size that Word shows as 12 points, and a two-font pairing where the Chinese text is set in 宋体, SimSun, and the Latin text in Times New Roman. That pairing is the whole reason a Western template looks wrong to a Chinese reader: Word falls back to a default CJK font when the template only names one, and the result is a document whose Latin and Chinese characters have visibly different weights. The table continues past the visible portion of the README, so the full style inventory lives in the template file itself and in the documentation, and the point for a user is that every value in it is a decision you can change once and inherit everywhere.

It is now an agent skill, with Windows install paths

The repository has grown an agent-facing surface, and that is the newest thing in it. A SKILL.md file makes the project usable from tools that support skills, and the README says the skill triggers when a user asks to convert Markdown to Word, to apply a Chinese Word template when exporting docx, or to convert a document with this repository's template, in Codex, Claude Code and similar agents. By default the skill uses the unnumbered-heading, flush-list template and loads the markdown-to-docx.lua filter, which means the agent applies both halves at once. Installation has two documented routes. The first is to ask the agent to install the skill from the repository URL, and the second is to create a directory under the user profile, one path for Codex and one for Claude Code, and put the skill files there. The repository also has an agents directory, a scripts directory and a CHANGELOG, and a README.docx, which is this README exported through the tool it documents, which is a small and convincing detail. For the manual routes in the note applications, the pattern is the same everywhere: find the export settings, choose Word, and set the custom argument to the reference document path. Typora takes a style file path in its preferences, SiYuan takes the pandoc execution parameters, and Obsidian needs its enhancing export plugin first.

Against a template you build, and against exporting to PDF instead

There are two honest alternatives. The first is to make your own reference document, which is a morning's work once you know the rule about editing styles rather than paragraphs, and it gives you a template that matches your house style exactly with no Lua filters to maintain. The cost is that you then own the caption convention, the HTML problem and the inline code problem, and the project's filters are a working reference implementation of all five. The second alternative is to stop exporting to Word. Most readers of a Markdown note never open a docx, and pandoc's own PDF or HTML output is a one-line command with no template involved, at the price of the CJK font handling and the page layout that a Word template gives you. The failure mode to watch for is a workflow that has grown several document conventions over years, each encoded in a paragraph's direct formatting, which no reference document can fix. That is the case where this repository saves you the most time, because the filters rewrite the document structure rather than restyle it.

Editorial conclusion

Adopt pandoc_docx_template if you write Markdown in a note app, export to Word regularly, and are Chinese-speaking or otherwise need CJK typography that pandoc will not give you by default, because the filters solve five defects that no reference document can solve on its own. Do not adopt it if you export to PDF or HTML, since the entire mechanism is Word styles. Verify four things before you rely on it: that the output opens correctly in the Word you actually use, as the README states the templates are tested only in Office Word on Windows and may not work in WPS or Office on macOS, that you understand the reference document is chosen with --reference-doc and that changing it changes the styles, that the Lua filter you need is the one you want, since the combined markdown-to-docx.lua applies the whole set, and which template variant you picked, since heading numbering and list indent are separate options rather than settings. There is no LICENSE file at the repository root, no GitHub releases, and the last push was 2026-07-09.

Frequently asked questions

Official sources

1. Achuan-2/pandoc_docx_template on GitHub
2. Issues
3. README