Word-Formatter-Pro: one-click formatting for Chinese office documents

The rules are gongwen conventions, not a generic Word style

Word-Formatter-Pro is a desktop application for laying out official documents, reports and ordinary Word files. It takes badly formatted Word or WPS documents, plain text or Markdown and turns them into standardised .docx output, and the README is explicit that it is aimed at batch processing and everyday office work rather than at one document at a time.

The built-in defaults are the important part. They reference the common layout standards for Chinese official documents, and they cover page margins, page numbers, fonts, font sizes, line spacing and heading levels. That is a narrower claim than a formatting tool usually makes, and it is the reason the tool exists: the conventions are stable and widely known, which makes them a good target for automation, and a human applying them by hand to a thirty page report is exactly the work that gets done badly.

The workflow is deliberately blunt. You add a file, a folder or paste text directly into the window, and you click the start button. For pasted text the tool defaults to A4 paper. The application is written in Python, licensed under MIT, and the releases are frequent, with v2.7.8 published on 2026-10-14, v2.7.7 on 2026-08-22 and v2.7.6 on 2026-06-06. The last push was on 2026-10-14, and the repository has a GitHub Releases page and a mirrored Gitee Releases page, which is a sensible choice for a tool whose users are largely inside mainland China.

The application ships as a .exe on Windows, an .AppImage on Kylin and Linux, and a zipped .app for Apple Silicon Macs, with before and after screenshots for both Word and text input in the repository.

Heading levels, captions and attachments are inferred, not declared

The most substantial engineering in the project is the recognition layer, and it is where a reader should look before trusting an output.

Titles are found by position and shape. A run of consecutive centred paragraphs at the start of the document with the same font and size is treated as the main title, and a centred paragraph below it with a different font and size is treated as the subtitle. For text and Markdown input the rule is simpler: the first paragraph that is not a heading marker becomes the title.

Then four heading levels are recognised, distinguished by the markers Chinese documents use: the ideographic numeral with a dun hao, its parenthesised form, an Arabic numeral with a dot, and the parenthesised Arabic numeral. Each gets its own format and its own outline level. The harder case is a second-level heading that shares a paragraph with the body text, where the heading and the following sentences sit in one paragraph; the tool splits them within the paragraph and formats the two parts separately.

Captions are located by proximity and alignment. For an image or a table, the tool looks for the nearest centred caption above or below it, marked with the Chinese characters for figure or table, and applies the matching caption format. Attachment markers are recognised as well, including the plain form and the numbered or colon forms, and the tool sets a page break before them and then looks for a title and subtitle inside the attachment. There is a detail worth noting: when an attachment marker has no title or subtitle after it, the tool does not skip the body paragraph that follows, which is a specific bug class that automated formatters usually get wrong.

The cost of inference is that all of this is a heuristic. If your documents use a different marker convention, the levels will not line up, and the tool gives you no signal that it guessed wrong.

Originals are never modified, and the copy handling is deliberate

The safety story is a selling point, and the README describes it in enough detail to be reassuring.

The original file is not modified directly. The program works on a safe copy in the system temporary directory, or on the converted .docx, and those temporary files are named with the process ID and a random suffix, which lowers the risk of two files colliding and overwriting each other. For an office tool that processes a folder of files in the background, that is the detail that matters most, and it is unusual to see it stated explicitly.

The second safety concern is not touching content it does not understand. When it unifies fonts and sizes, it tries to preserve the original bold, italic, underline and font colour. Paragraphs that contain images, drawings or embedded objects are not restructured, only the text inside them is formatted, and paragraph properties that could make an image render incompletely, such as line spacing, are left alone. When it cleans whitespace at the start of a paragraph, it avoids deleting runs that contain field codes, bookmarks or comment references, since those are the parts of a Word document that a naive text operation destroys.

A third guard is a user interface one. Adding or dragging in a folder with more than a thousand files raises a confirmation dialog first, because a deep directory tree turns into a long scan with no obvious progress. Formatting runs on a background thread, so the log keeps scrolling and the window stays responsive, and closing the window during a job asks for confirmation and tries to flush the remaining log lines.

Taken together, these are the decisions that separate a tool you can point at a shared drive from one you run on copies.

What you can process depends on the platform you run it on

The tool accepts .docx, .txt and .md everywhere, and .doc and .wps where the platform allows it, and the differences are worth understanding before you build a workflow on it.

On Windows the tool prefers Word or WPS automation through COM, which means it can accept tracked changes and convert automatic numbering into literal text. On macOS, Kylin, UOS and Linux it looks for the LibreOffice soffice binary to convert the old formats. If LibreOffice is not installed, the .doc and .wps files are skipped and recorded as skipped, and the other formats continue to be processed. The GUI, the CLI and the skill can all find soffice automatically, and the CLI accepts a path to it as an option.

That fallback has a behavioural edge. The Python conversion of automatic numbering, which is the default on the non-Windows platforms and can be switched off globally, does not accept tracked revisions. The README says the unsupported numbering is kept and a warning is recorded, so the result is a document with literal numbers where it could, and a warning where it could not. On Windows the same task goes through Word itself, which is a different code path with different results.

Two more input details are worth noting. Markdown cleanup strips heading markers, bold and italic markers, links, image syntax, quotes and horizontal rules, but numbered items such as 1. or 1.2.3 are kept as they appear in the source and are not renumbered automatically, so a Markdown file with an odd list will produce an odd document. And text and Markdown input gets three blank line policies, with the default being to delete single blank lines and collapse runs of blank lines down to one, which is what most people mean by tidying a text file.

A CLI and a self-contained skill sit next to the GUI

The core is split into separate files at the repository root, and the README is explicit that this was done for maintainability, for command line use and for reuse as a skill. The layout makes that visible: a core module, a configuration module, the GUI module, the CLI module, a version module, and several test modules, including separate ones for the numbering logic with samples and integration tests.

The CLI script accepts a single file, multiple files, a repeated input option, positional arguments and a directory, with directory input recursive by default and the output directory preserving the original structure. It reads a configuration file named wfp_config.json from the current directory automatically, and it accepts a path to a configuration file, inline configuration JSON, and key and value overrides for individual settings.

The built-in tests are runnable from any of the three entry points, which is a good sign for a project where the GUI and the CLI share the core:

python wfp.py --test
python wfp_cli.py test

The skill packaging is the unusual part. A directory named skills/doc-format contains a scripts folder with the complete CLI, the core logic, the default configuration and the tests, so the folder can be installed on its own and still run. For a team that wants to apply the same document rules from a larger tool or an assistant environment, that self-containment is the point: there is no import path back to the original repository.

The technical housekeeping behind this is worth a sentence too. The regular expressions used for text recognition, Markdown cleanup, heading detection, attachment detection and table number checks are precompiled at module level, so a batch run does not recompile them inside the loop.

Configuration is a tree of switches, with experimental parts marked as such

The parameter list in the README is long, and reading it tells you what the author considers fiddly in real documents.

Page setup covers the four margins, the footer distance, the page number alignment and the page number font, plus an option to force A4. The heading and body styles are set per level, for the title, the subtitle, the first and second level headings, and the body text including the third and fourth levels. Indentation gets its own repair rule: residual left indent, hanging indent and fixed first line indent are cleared before the standard first line indent is applied, which prevents indents from stacking when a document has been through several tools already.

Fonts are offered as a list of recommended fonts with the system installed fonts below them, separated by a divider line, and the text field still accepts a font name that is not listed. There is a separate option to give Western letters and digits their own font, with Times New Roman as the default, otherwise digits and Latin letters follow the font of the surrounding text.

Two features are labelled experimental, and that label is the honest signal. Symbol standardisation conservatively fixes mixed Chinese and Western punctuation, including commas, full stops, semicolons, colons, question marks, exclamation marks, brackets, quotes and ellipses. Table content formatting sets table fonts, size, line spacing, row height, width and borders and can adjust column widths automatically, with the sub-options greyed out while the master switch is off.

Table alignment is separate from that: when enabled, headers, index columns and short text are centred, numbers are right aligned and long text is left aligned, and the original cell alignment is preserved by default. That combination of dependent switches, greyed-out sub-options, a load, save, save as default and restore built-in defaults configuration manager, and a progress bar with a log panel is what a tool that a non-programmer runs for ten minutes at a time needs.

Editorial conclusion

Adopt Word-Formatter-Pro if you produce Chinese official documents or reports in bulk and the layout rules are the same every time, because the built-in defaults encode the margin, page number, font, size and line spacing conventions that a gongwen template would carry. Do not adopt it as a general Word formatter, because the heading and caption recognition is tuned to Chinese document conventions and will not map cleanly onto an English template, and because old.doc and.wps files are skipped and recorded as skipped on platforms without LibreOffice. Before you run it over a folder, check the conversion path on your own machine, since accepting tracked changes and converting automatic numbering is done through Word or WPS automation on Windows and falls back to a Python conversion elsewhere that leaves revisions alone.

Frequently asked questions

Official sources

1. cwyalpha/Word-Formatter-Pro on GitHub
2. Issues
3. License: MIT
4. README
5. Releases