English ยท ็ฎไฝไธญๆ ยท ็น้ซไธญๆ ยท Deutsch ยท Franรงais ยท Espaรฑol ยท Portuguรชs ยท ะ ัััะบะธะน ยท ๆฅๆฌ่ช ยท ํ๊ตญ์ด ยท Tiแบฟng Viแปt ยท ุงูุนุฑุจูุฉ
DocWen converts office files locally. Use it to turn Word files into Markdown, export Markdown to Word, extract text and tables from PDFs, or clean up files for a report. It has a desktop interface for everyday work and a command line for repeatable tasks.
Documents arrive in different formats, and reformatting them by hand takes time. DocWen helps when you need to:
- Convert Word and Markdown in either direction, including headings, tables and formulas where the selected route supports them.
- Turn Excel spreadsheets into Markdown tables, or produce spreadsheets from Markdown.
- Extract text and images from PDFs, XPS and OFD files; use offline OCR where available. OCR can make mistakes, so check the original.
- Merge or split PDFs, convert common image formats, and use your own Word or spreadsheet templates.
- Check Markdown or Word text with your own spelling, symbol and punctuation rules.
- Process one file in the desktop app, or script a batch using the CLI.
DocWen handles DOCX, XLSX, PDF and several older office and image formats. Availability depends on the operation, platform and installed conversion software: not every format converts to every other format. Check the capability reference for details.
For specific steps, use the CLI reference, format capabilities, Markdown compatibility notes, or troubleshooting. This page gives an overview before the detailed examples below.
DocWen processes files on your computer rather than uploading them to a conversion service. Its Python process blocks dependency network calls, while external Office, WPS and LibreOffice processes follow their own system network policies. For sensitive work, keep those programs and your operating system configured accordingly.
Import a Word document and choose Markdown export options.
Import Markdown and choose a template to generate a Word document.
Changelog: see CHANGELOG.md
Download the matching archive from Releases. Packages support Windows x64, Ubuntu 24.04 x64 and Apple Silicon macOS 14+. No Python installation is required. Extract the complete archive: on Windows open DocWen.exe; on Ubuntu run ./DocWen; on macOS move DocWen.app to Applications and follow the first-launch guide. Ubuntu and macOS also have separate CLI-only archives. Other Linux distributions and Intel Macs are not package targets.
Release assets vary by version; choose an archive actually listed for your system. Older releases may not include macOS packages.
For development or a source installation, install Python 3.12 and uv 0.12.0, then run these commands from the repository:
git clone https://github.com/ZHYX91/docwen.git
cd docwen
uv sync --frozen --all-extras
uv run --frozen docwen-gui
uv run --frozen docwen --helpUse uv run --frozen to run commands in the synchronized environment without activating it. CI and production builds use uv 0.12.0; dependency maintenance accepts compatible 0.12.x versions. pip install -e is unsupported because pip cannot apply this repositoryโs scoped dependency exclusion.
Download the macos-arm64 archive for Apple Silicon Macs running macOS 14 or later.
The desktop archive contains DocWen.app; move the whole app to Applications.
Mac packages retain ad-hoc signatures and are not Developer ID signed or notarized.
First launch may require System Settings โ Privacy & Security โ Open Anyway after an
attempted launch. See macOS installation and first launch
for checksum checks, CLI use and update instructions.
LibreOffice support (Optional)
To convert legacy formats like .doc and .xls, install LibreOffice:
Download: https://www.libreoffice.org/download/
HEIC/HEIF images
Packaged apps use their bundled image backend. Check the installed build with DocWenCLI doctor --json (use the CLI path below on macOS); installing pillow-heif into system Python does not change the app. For source installs, uv sync --frozen --all-extras already installs pillow-heif. On macOS, install libheif with brew install libheif if the backend reports that the native library is missing, then check again with uv run --frozen docwen doctor --json. Availability still depends on the actual build and backend.
Supported package target: DocWen supports the packaged GUI and CLI on Ubuntu 24.04 x64. These prerequisites do not extend that support claim to another Linux distribution or architecture.
- Desktop environment installed (GNOME, KDE, XFCE, etc.)
- GUI uses PySide6 (Qt6). If startup fails due to missing system libraries, install the Qt runtime dependencies indicated by the error (commonly OpenGL/X11 related).
- For headless Ubuntu 24.04 systems, run
./DocWenCLIfrom the CLI-only archive, oruv run --frozen docwenfrom a source checkout.
-
Prepare a Markdown File:
--- title: Test Document --- ## Test Title This is the test body content.
-
Drag and Drop Conversion:
- Launch the program.
- Drag the
.mdfile into the window. - Select a template.
- Click "Generate DOCX".
-
Get Results:
- DocWen saves the single Word document directly at the configured output location. Use Open Output to find it.
Tip: You can use the sample files in the samples/ directory to quickly try out the software's features.
Task options appear when a request starts and come from that request. Search templates by name or usage hint; Recently used in this session lists templates used by started tasks and does not change your default. For spreadsheet aggregation, see merge scope, modes and result checks.
The program uses an adaptive three-column layout:
| Area | Description | Display Timing |
|---|---|---|
| Center Column (Main Area) | File drag-and-drop area, operation panel, status bar | Always shown |
| Right Column | Template selector / Format conversion panel | Automatically expands after selecting a file |
| Left Column | Batch file list (grouped by type) | Shown when switching to batch mode |
- Launch Program: Double-click
DocWen.exe(Windows packaged release) or runuv run --frozen docwen-gui. - Import File:
- Method 1: Drag and drop files directly into the window.
- Method 2: Click the "Add" button in the drag-and-drop area to select files.
- Select Template (if conversion is needed): The right template panel expands automatically; select a suitable template.
- Configure Options: Check the required conversion/export options in the operation panel.
- Execute Operation: Click the corresponding function button (e.g., "Export Markdown", "Generate DOCX", etc.).
- View Result: The status bar shows progress and results; click the "Open Output" action on the right to open the output location.
The program supports two processing modes, switchable via the toggle button in the file drag-and-drop area:
Single File Mode (Default):
- Process one file at a time.
- Simple interface, suitable for daily use.
Batch Mode:
- Import multiple files simultaneously.
- Left column shows categorized file list (grouped by document/spreadsheet/image, etc.).
- Supports batch adding, removing, and sorting.
- Clicking a file in the list switches the current operation target.
The operation panel automatically adjusts available options based on file type:
| File Type | Available Operations |
|---|---|
| Word Document | Export MD, Convert PDF, Text Proofreading, OCR |
| Markdown | Convert DOCX, Convert PDF, Text Proofreading |
| Excel Spreadsheet | Export MD, Convert PDF, Table Summary |
| PDF File | Export MD, Merge, Split, OCR |
| Image File | Format Conversion, Compression, OCR |
| HTML/EPUB/PPTX etc. | Export MD |
Click the settings icon at the bottom of the window or press Ctrl+,.
The sidebar groups related settings under headings. In a short window it scrolls vertically, keeping every page reachable; a narrow window uses a page selector instead. Switching layouts preserves the selected page. When the sidebar has keyboard focus, Up / Down switch pages, Home / End select the first or last page, and Tab enters the selected page. Group headings are not selectable.
Under General โ Appearance, choose Small / Standard / Large text and 90 / 100 / 110 / 125 / 150% interface scale. Scaling is relative to the system setting: system 200% with application 90% gives a nominal 180%. Changes preview immediately; Apply or OK saves them, and Cancel restores the last saved appearance.
Settings are organized into Basics, Input types, Content and Specialized. The OCR and images page controls shared recognition and Markdown image output; per-input OCR defaults stay on the corresponding input pages. Image format conversion and compression remain on Incoming images.
Optimization choices appear only when an available optimization supports both the current interface language and the detected input format, including any required conversion software. Settings show the corresponding pages only for applicable optimizations. The built-in official-document and Chinese-invoice optimizations currently support only the Simplified Chinese interface (zh_CN). In other interface languages, their choices and pages are hidden and saved defaults are not applied; the saved preferences are kept for switching back. This controls GUI discovery and defaults, not an explicitly selected CLI or Machine task.
For all interface languages, Incoming text โ Heading Numbering (Markdown to Document) has one output-mode choice: Text writes the new number into the heading; DOCX native uses Wordโs multilevel numbering. Comment on newly added heading numbers is independent and works in either mode. Text-mode comments mark the added number; native-mode comments mark the first visible heading character. Enable heading numbering separately.
When available, the Specialized group has dedicated Official documents and Invoices pages. Official document settings separate Document โ Markdown recognition defaults from Markdown โ Document template field formatting. The field toggle has an information button describing attachment notes, copied recipients, dates, annotations and supported placeholder positions.
Separately, Markdown โ Document Chinese official-document field formatting is controlled by template_fill.gongwen_fields_enabled (on by default), independently of interface and task output language. Hiding the Official documents settings page does not disable this formatter. It formats fixed Chinese template fields, not Document โ Markdown recognition.
Invoices have separate defaults for PDF / OFD โ Markdown and Image โ Markdown. A default only sets the initial choice for compatible files; it does not classify a file as an official document or invoice. Each input category has one default: Set as default replaces its previous choice, while Clear default removes the current page's choice. Apply or OK saves these changes; Cancel discards the draft. Shared extraction and OCR settings remain on their own pages, with links from the optimization pages. Invoice images always use OCR; scanned PDFs require OCR enabled in the incoming fixed-layout settings, and OFD reads existing text and structure without OCR for scanned content.
Interface language controls application text and layout. Task output language independently controls generated labels, document styles and proofreading comments; it does not translate body text. Changing the interface keeps saved template choices and output language. OCR Auto follows the task output language; choose an OCR language explicitly when needed. See language settings.
Generate Markdown controls output syntax and extensions; Parse Markdown controls input recognition, extensions and Markdown-to-Word mappings. The visible help describes current support: output extensions and preferred syntax are not yet implemented uniformly across all source formats or specialized optimizers. Enabling an extension does not add recognition capabilities.
Under Parse Markdown, Each line as a paragraph optionally turns ordinary prose lines into separate Word paragraphs. It is off by default; lists, quotes, code, semantic structures and explicit Markdown hard breaks retain their own boundaries.
Scope: The specialized field formatter targets Chinese official-document conventions, and the invoice extraction optimization targets Chinese invoice formats. Other documents can still use the regular conversion paths.
- Drag External File: Drag directly into the window to import.
- Open Output: Click the "Open Output" action on the right side of the status bar to open the output location.
- Right-click Template Item: Choose Open file location to show the template in its folder.
CLI examples use docwen as the command name. From this source checkout, prefix it with uv run --frozen; in a downloaded package, use DocWenCLI.exe (Windows) or ./DocWenCLI (Linux/macOS).
Use the command line (CLI) to inspect files, convert them from a terminal, or automate repeated tasks. For integrations with other apps, use the Machine Protocol described below.
For terminal use and local automation scripts, use this order:
inspect <file> [--json]: detect the real file category, format, and supported actions first.resources list formats --json: check which conversions are available and whether required software is installed.schema convert: read the accepted conversion options, defaults and requirements.convert <file> --to <fmt> (--output-dir <dir> | --output <path>) --dry-run --json: check the detected format, conversion method and options without writing files.convert <file> --to <fmt> (--output-dir <dir> | --output <path>) ...: run the actual conversion after the preview is acceptable.
Apps and plugins connect through serve --stdio using Machine Protocol v2 to discover operations, plan a task and run it. This is the supported API for integrations; CLI --json is intended for terminal scripts. Use gui open|activate|status to open files in the desktop app or bring its window to the front. See the CLI guide and integration protocol for details.
Conversions to Markdown always publish a result folder inside the parent selected with --output-dir DIR. Conversions from Markdown that produce one final document or spreadsheet save it directly in that parent; multiple output files or an explicitly requested audit sidecar use a result folder. Generated names include the source name, timestamp and current input format. Use --output PATH for one exact final file, including one generated from Markdown; grouped results require --output-dir.
# Packaged release (Windows)
DocWenCLI.exe inspect document.docx --json
# List the accepted conversion options
DocWenCLI.exe schema convert
# Preview how the conversion would run without writing files
DocWenCLI.exe convert report.docx --to md --output-dir exports --extract-img --ocr --dry-run --json
# Export Word to Markdown (extract images + OCR)
DocWenCLI.exe convert report.docx --to md --output-dir exports --extract-img --ocr
# Markdown to Word (select a template and heading/body merge mode)
DocWenCLI.exe convert document.md --to docx --output-dir exports --template template.docx.f1eeb0a008ce3eae0619ecae6e185ab132a3ee0abdd382c8863481d9af1dc77f --heading-merge-mode punct_required
# Markdown to Word, then proofread the generated DOCX before saving it
# --check is valid on convert only together with --proofread.
DocWenCLI.exe convert document.md --to docx --output-dir exports --proofread --check typo --check punct
# Control Markdown image export mode and OCR placement
DocWenCLI.exe convert report.docx --to md --output-dir exports --extract-img --image-mode file --ocr --ocr-placement image_md
# Chinese official-document optimization selected by public resource ID
DocWenCLI.exe convert report.docx --to md --output-dir exports --optimization gongwen
# Chinese invoice optimization selected by public resource ID
DocWenCLI.exe convert invoice.pdf --to md --output-dir exports --optimization invoice_cn
# Check available conversions and required software
DocWenCLI.exe doctor --json
DocWenCLI.exe resources list formats --json
# Read-only proofreading; add --report only when an output is wanted
DocWenCLI.exe validate document.docx --check typo --check punct --json
DocWenCLI.exe validate document.docx --check typo --check punct --report reviewed.docx
DocWenCLI.exe validate input.md --check typo --check punct --report report.json
# From source / uv
# inspect -> resources -> schema -> dry-run -> convert
# docwen inspect document.docx --json
# docwen resources list formats --json
# docwen schema convert
# docwen convert document.docx --to md --output-dir exports --dry-run --json
# docwen convert document.docx --to md --output-dir exportsThe table below lists common commands only. For the full command surface, use docwen --help (source / uv) or DocWenCLI --help (packaged release).
| Command / Option | Description |
|---|---|
convert <file> --to <fmt> (--output-dir <dir> | --output <path>) |
Convert one file. Markdown output and grouped results require --output-dir; one final file, including from Markdown, may use exact --output. Existing targets require explicit --overwrite. |
convert <file> --to <fmt> ... --dry-run --json |
Check the detected format, conversion method and options without writing files. |
convert <markdown> --to docx --output-dir <dir> --proofread [--check ...] |
Generate DOCX, proofread it, then save the result. --check without --proofread is rejected; omitting --check uses configured proofreading defaults. |
convert <file> --to <fmt> ... --optimization <id> |
Select an optimization by the public resource ID returned by resources list optimizations. |
validate <file> --check ... [--report <path>] |
Proofread DOCX, Markdown, or legacy Word-family content. The default is read-only; --report writes annotated DOCX for document input or JSON for Markdown. |
number markdown <file> --operation add|remove (--output <path> | --in-place) |
Explicitly add or remove Markdown heading numbering. |
merge pdf|tables|images <files...> --output <path> |
Combine PDFs, spreadsheets or images into one output. |
split pdf <file> --pages <range> --output-dir <dir> |
Split selected PDF pages into an explicit directory. |
batch convert|validate <files...> |
Run an explicit multi-file conversion or proofreading operation. |
schema convert |
List accepted conversion options, defaults and requirements in a form scripts can read. |
inspect <file> [--json] |
Inspect file category/format, recommended actions, and extension/content mismatch warnings. |
doctor --json |
Check the installation, available conversions and required software. |
resources list formats --json |
List supported conversions, required software and current limitations. |
resources list optimizations --json |
List optional optimizations and the conversions they apply to. |
resources list templates [--target docx|xlsx] |
List available templates. |
resources list numbering-schemes |
List available numbering schemes. |
gui open [ABSOLUTE_FILE] [--timeout <seconds>] [--json] |
Open the DocWen window and optionally load a file. Use an absolute file path. |
--template <id> |
Use the resource ID returned by resources list templates, rather than a template name or path. DOCX IDs apply to docx/doc/odt/rtf/wps/pdf, XLSX IDs to xlsx/xls/ods/csv. CSV export writes table data directly when no template is selected. With an XLSX template, DocWen fills the workbook first and creates one CSV per worksheet. |
--extract-img / --no-extract-img / --ocr |
Image extraction and OCR options for convert --to md. |
--image-mode file|base64|embed|omit |
Control how images are emitted during Markdown export. |
--ocr-placement image_md|main_md |
Control whether OCR text is written to image-side Markdown or the main Markdown file. |
--heading-merge-mode punct_required|always|never |
Control the heading + body merge strategy for convert --to docx. |
--optimization <id> |
Apply an optimization from resources list optimizations. |
--jobs / --continue-on-error |
Controls provided by explicit batch subcommands. |
--json / --quiet / --timing |
Show JSON output, reduce logs, or include elapsed time in terminal scripts. |
Using Obsidian Markdown extensions? Four extensions are optional and disabled on a new DocWen installation: structural_tables (merged cells and multi-row/row headers), captions_references (Number Suite captions and references), extended_headings (H7โH9), and typed_endnotes (typed endnotes).
- Markdown โ Word: Open Settings โ Parse Markdown and enable the extensions your notes need, or click Use Obsidian extensions for the input direction. Otherwise special markers may remain literal text.
- Word โ Markdown: Enable the corresponding output extensions in Settings โ Generate Markdown (or use the preset there). With them off, structures may be flattened or normalized and a warning reported.
Keep the original Markdown and inspect the produced DOCX. Word numbering follows DocWen's conversion settings; the round trip does not promise identical source spelling or whitespace. See the Markdown compatibility reference for exact boundaries.
Markdown headings map directly to Word heading levels:
- Document title and subtitle are placed in YAML metadata.
- Markdown
# Heading 1corresponds to Word "Heading 1". - Markdown
## Heading 2corresponds to Word "Heading 2". - Levels 1โ6 use standard Markdown syntax. For levels 7โ9, enable Extended headings in the Markdown input settings and use seven to nine leading
#markers.
Tip: If you prefer using Markdown's first-level heading (#) as the document title, starting from second-level headings (##) for body headings, you can style "Heading 1" in the Word template to look like a document title (e.g., centered, bold, larger font size), and select a numbering scheme that skips first-level heading numbering in the settings. This way, your first-level headings will appear as document titles.
Basic Rule: Ordinary Markdown soft line breaks do not create separate Word paragraphs by default. Enable Each line as a paragraph under Settings โ Parse Markdown to split ordinary prose lines. Lists, quotes, code, other semantic structures and explicit hard breaks retain their own rules.
Mixed Paragraphs: When a subheading needs to be mixed with the body text in the same paragraph (default mode: "Punctuation required"), the following conditions must be met:
- The subheading ends with one of the configured trigger characters. The exact default is
ใ๏ผ๏ผ๏ผ.:!?(full-width or half-width period, colon, question mark, or exclamation mark). - The body text is located on the immediate next line of the subheading.
- The body text line cannot be a special Markdown element (such as headings, code blocks, tables, lists, quotes, formula blocks, separators, etc.).
Example:
## I. Work Requirements.
This meeting requires all units to earnestly implement...The above two lines will be merged into the same paragraph, where "I. Work Requirements." keeps the subheading format, and "This meeting..." keeps the body text format.
Note:
- There cannot be an empty line between the subheading and the body text; otherwise, they will be recognized as separate paragraphs.
- By default ("Punctuation required" mode), if the subheading does not end with a terminating punctuation mark, it will not merge with the next line even without an empty line.
- The trigger-character field is editable in the Incoming text settings. An empty value disables merging in "Punctuation required" mode. Commas, semicolons, enumeration commas, dashes, and ellipses are deliberately excluded from the default, but users may add them explicitly.
- You can change this in Settings โ Incoming text โ "Markdown to Document โ Format Processing" โ "Heading + body merge mode".
Supports bidirectional conversion between Markdown separators and Word page breaks/section breaks/horizontal lines:
- DOCX โ MD: Word page breaks, section breaks, and horizontal lines are automatically converted to Markdown separators.
- MD โ DOCX: Markdown
---,***,___are automatically converted to corresponding Word elements. - Configurable: Specific mapping relationships can be customized in the settings interface.
Supports GFM task list items in both directions:
- [ ] Todo
- [x] Done- MD โ DOCX: Renders as a bullet list with
โ/โtext prefix. - DOCX โ MD: Converts list items starting with
โ/โ/โback to- [ ]/- [x]. - Font note:
โ/โmay not render in some fonts. If needed, use fonts like "Segoe UI Symbol" in your Word template.
Supports Obsidian/Wiki and standard Markdown image embeds, with optional sizing (px):
![[image.png]]
![[image.png|300]]
![[image.png\|300]]


- No size: uses the original image size, capped by available page/cell width
- With size: allows upscaling, still capped by available width
- Image-only paragraph: uses the Image paragraph style (centered, single spacing)
Supports clickable links in Markdown -> DOCX:
[Docwen](https://example.com)
[[Target]]
[[Target|Open target]]
<https://example.com>
<user@example.com>- Markdown links and Wiki links are written as Word hyperlinks by default
- Wiki links resolve to local
file:///links when the target file is found - Angle-bracket autolinks support
https://...and emailmailto:... - Bare URLs become clickable in Word only when
[non_embed_links].auto_link_bare_urlis enabled inconfigs/link.toml; this option is off by default - Markdown -> XLSX keeps the original link syntax instead of emitting DOCX hyperlink placeholders
- Drag the
.docxfile into the program window. - Choose the export options, then click Export Markdown.
- Generates a
.mdfile containing YAML metadata.
Supported Formats:
.docx- Standard Word document..doc- Automatically converted to DOCX for processing..wps- WPS document automatically converted..rtf,.odt- Converted to DOCX before processing. These formats,.docand.wpsrequire a compatible local Office conversion program.
Export Options:
| Option | Description |
|---|---|
| Extract Images | If checked, images in the document are extracted to the output folder, and image links are inserted into the MD file. |
| Image OCR | Recognize text in images. Save it in a Markdown file for each image or in the main Markdown file, according to the OCR output setting. |
| Optimize for document type | Apply an optimization for the selected document type, such as extracting fields from Chinese official documents. Leave this off to use the standard conversion. The built-in Chinese official-document and Chinese-invoice export optimizations are offered in the GUI only with the Simplified Chinese interface (zh_CN) and a compatible input route. This GUI restriction does not block explicit CLI/Machine selection of gongwen or invoice_cn. |
| Remove existing heading numbers | If checked, removes numbers before subheadings (e.g., "ไธใ", "๏ผไธ๏ผ", "1.", etc.) and converts them to pure title text. |
| Add heading numbers | If checked, automatically adds numbers based on heading levels (numbering scheme can be configured in settings). |
Word/WPS heading numbers created with multilevel lists are preserved during export. Enable Remove existing heading numbers to remove those numbers while keeping the heading levels.
- Prepare a
.mdfile. Add a YAML header if you want to supply a title or custom fields. - Drag it into the program window and select the corresponding Word template.
- Click Generate DOCX to fill the template and save the document.
Conversion Options:
| Option | Description |
|---|---|
| Remove existing heading numbers | If checked, removes numbers before subheadings. |
| Add heading numbers | If checked, automatically adds numbers based on heading levels. |
Note: If there are paragraphs where subheadings and body text are mixed, strict line breaks must be maintained in the MD file (see "Line Breaks and Paragraphs" above).
The converter automatically detects and processes template styles during Markdown โ DOCX conversion:
Paragraph Style: Applied to the entire paragraph.
| Style | Detection Behavior | Injection when Missing | Source |
|---|---|---|---|
| Heading (1~9) | Detects paragraph style | Template heading styles | Word Built-in |
| Code Block | Detects paragraph style | Consolas font + Gray background | Defined by Software |
| Quote (1~9) | Detects paragraph style | Gray background + Left border | Defined by Software |
| Formula Block | Detects paragraph style | Formula specific style | Defined by Software |
| Separator (1~3) | Detects paragraph style | Bottom border paragraph style | Defined by Software |
Character Style: Applied to selected text.
| Style | Detection Behavior | Injection when Missing | Source |
|---|---|---|---|
| Inline Code | Detects character style | Consolas font + Gray shading | Defined by Software |
| Inline Formula | Detects character style | Formula specific style | Defined by Software |
Table Style: Applied to the entire table.
| Style | Detection Behavior | Injection when Missing | Source |
|---|---|---|---|
| Three-Line Table | User config priority | Three-line table style definition | Defined by Software |
| Grid Table | User config priority | Grid table style definition | Defined by Software |
Numbering Definition: Used for list formats.
| Type | Detection Behavior | Handling when Missing |
|---|---|---|
| List Numbering | Scans existing ordered/unordered list definitions in template | Uses decimal/bullet preset |
- Word Built-in Styles (heading 1~9):
- Style names use Word standard English names (e.g.,
heading 1). - Word automatically displays localized names based on system language (e.g., "ๆ ้ข 1" on Chinese systems).
- Style names use Word standard English names (e.g.,
- Software Defined Styles (Code Block, Quote, Formula, Separator, Table, etc.):
- New managed style names use Task output language in General settings, not interface language. Switching interface language does not rename styles already in the selected template.
Suggestion: After customizing styles in the template, the converter will automatically use your styles; if not present in the template, it will use built-in preset styles.
- Excel/CSV to Markdown: Add an
.xlsxor.csvfile and click Export Markdown. - Markdown to Excel/CSV: Export Markdown tables directly, or choose an XLSX template to fill YAML fields, tables and images. Template formatting, existing merged cells and cell protection are handled during conversion. With a template, CSV export creates one file per worksheet.
Supported Formats:
.xlsx- Standard Excel document..xls- Automatically converted to XLSX for processing..et- WPS spreadsheet automatically converted..csv- CSV text table..tsv- TSV tab-separated table.
The program provides four customizable proofreading rules:
- Punctuation Pairing Check - Detects if paired punctuation like parentheses and quotes match.
- Symbol Proofreading - Detects mixed use of Chinese and English punctuation.
- Typo Check - Checks for common typos based on a custom dictionary.
- Sensitive Word Detection - Detects sensitive words based on a custom dictionary.
Custom Dictionaries: Visually edit typo and sensitive word dictionaries in the "Settings" interface.
Usage:
- Drag the Word or Markdown document to be proofread into the program.
- Check the required proofreading rules.
- Click the "Proofread" button.
- For Word documents, proofreading results are displayed as comments in the document. For Markdown files, results are output as a structured JSON report.
From the command line, use validate <file> to check a file without changing it. Add --report <path> to save the findings: Markdown produces a JSON report; Word and supported legacy document formats produce a DOCX with comments. --json changes how the command prints its result.
Manage DOCX/XLSX templates in Settings โ Templates. Built-in templates are read-only; custom templates use writable user storage. Enable, disable, sort and choose defaults here. MSIX users do not need to modify WindowsApps.
- Select a built-in template and choose Copy and edit, or import an existing DOCX/XLSX file.
- Edit the custom copy in Word, Excel or WPS; adjust styles and placeholders as described below.
- Save the file, return to DocWen and choose Refresh. No restart is needed.
YAML Field Placeholders: Use {{Field Name}} format in the template, which will be replaced by the corresponding value in the Markdown file's YAML header during conversion.
| Placeholder | Description |
|---|---|
{{Title}} |
Document title (Retrieval rules see below) |
{{Body}} |
Markdown body content insertion position |
| Others | Supports any custom field |
Title Retrieval Priority:
| Priority | Source | Description |
|---|---|---|
| 1 | YAML Title field |
Highest priority |
| 2 | YAML aliases field |
Takes the first element of the list, or string value |
| 3 | Filename | Filename without .md extension |
Multilingual Support: The title and body placeholders support multiple languages, e.g., title can be {{title}}, {{ๆ ้ข}}, {{Titel}}, etc., body can be {{body}}, {{ๆญฃๆ}}, {{Inhalt}}, etc.
Use an XLSX template to place YAML values, table rows or columns, and images in a spreadsheet. DocWen preserves existing merged cells and can recreate merges marked with < / ^ in Markdown. Check conversion warnings for protected cells. When exporting to CSV with a template, each worksheet becomes a separate CSV file.
1. YAML Field Placeholder {{Field Name}}
Used to fill a single value from the Markdown file's YAML header:
---
ReportName: 2024 Annual Sales Statistics
Unit: Sales Dept
---{{ReportName}}, {{Unit}} in the template will be replaced with corresponding values. The title field also follows the priority rules.
2. Column Fill Placeholder {{โField Name}}
Extracts data from the Markdown table and fills downwards row by row starting from the placeholder position:
| ProductName | Quantity |
|:--- |:--- |
| Product A | 100 |
| Product B | 200 |{{โProductName}} in the Excel template will be replaced by "Product A", and the next row will be filled with "Product B".
3. Row Fill Placeholder {{โField Name}}
Extracts data from the Markdown table and fills rightwards column by column starting from the placeholder position:
| Month |
|:--- |
| Jan |
| Feb |
| Mar |{{โMonth}} in the Excel template will be filled with "Jan", "Feb", "Mar" sequentially to the right.
Merged Cell Handling:
- Markdown -> Excel continues to preserve the template's original merged ranges.
- For known column-oriented template regions composed of contiguous
{{โField Name}}placeholders, the program can restore rectangular merges from explicit Markdown table</^markers. - Only cells whose trimmed content is exactly
<or^participate in merge detection;\<and\^remain literal text. - Invalid rectangles or conflicts with existing template merged ranges are downgraded to plain text with a warning instead of forcibly overwriting template structure.
Multi-table Data Merge: If there are multiple tables in Markdown using the same header name, data will be merged in order and filled sequentially.
A companion Obsidian plugin is published separately and works in tandem with the converter:
- ๐ One-Click Launch - Sidebar icon to quickly launch the converter.
- ๐ Automatic Handover - Automatically passes the currently open file path.
- ๐ Reuse the open window - Open another file in the running converter without restarting it.
DocWen Assistant supports Windows and Linux desktop hosts. Windows Microsoft Store installations can use automatic detection; Linux uses manual package selection. The Assistant does not currently support macOS.
- First click โ Launch the converter and open the current file.
- Click again with a file open โ Replace the current input with that file (single-file mode).
- Click again without a file open โ Bring the converter window to the front.
Install DocWen separately, then choose a published DocWen Assistant release compatible with your DocWen version. The Assistant does not install DocWen. Check its release notes instead of relying on a version number in this guide. Integrations use Machine Protocol v2 and Artifact Bundle v3.
docwen-openclaw lets OpenClaw convert and proofread local files through an independently installed DocWen. Check the published plugin releases for supported DocWen versions. For integration development, see Machine Protocol v2 and Artifact Bundle v3.
- Check if the file is occupied by another program.
- Confirm the file format is correct.
- Open Settings โ Logging to find the current log file and read the error details.
- Check that the template is enabled in Settings โ Templates and matches the selected output format.
- Confirm that the DOCX/XLSX file can be opened normally.
- Choose Refresh after external changes; use Import templates to add a file.
- For CLI
validate,.mdand.docxcan be checked directly. Legacy Word-family.doc,.wps,.rtf, and.odtinputs are also accepted after conversion to DOCX; check that the required local Office conversion software is available. - Check if the document contains editable text.
- Confirm proofreading rules are enabled in settings.
- Open Settings โ Templates. For a built-in template, use Copy and edit; for a custom template, use Edit.
- Adjust its styles in Word, Excel or WPS, then save and refresh the list.
- Select the custom template before generating new documents.
DocWen exports the last saved calculation result of a formula cell. If the spreadsheet has no saved result, the exported cell will be empty. This can happen with files created by another program or edited without recalculating and saving in Excel.
Solution:
- Open the file in Excel.
- Wait for formula calculation to complete.
- Save the file.
- Convert again.
DocWen processes files on your computer and has no file-upload, telemetry, online-download or network-service feature. It restricts network access by its own Python components. If this protection cannot start, DocWen does not continue running.
Separately launched programs such as Word/Office, WPS and LibreOffice, including helper processes, follow their own and the operating system's network settings. They are outside this restriction, so check their settings as well when working with sensitive files.
See how network protection works for its implementation and limits, or troubleshooting if the program cannot start or a conversion fails.
This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
- This project uses PyMuPDF (licensed under AGPL-3.0), so the entire project is also licensed under AGPL-3.0.
- The current GUI can use
PySide6-Fluent-Widgets(QFluentWidgets) on supported host paths; this dependency follows aGPLv3 / commercialdual-license model, while this repository continues to distribute under AGPL. - You are free to use, modify, and distribute this software.
- If you modify this software and provide services over a network, you must provide the modified source code to users.
- For detailed license information, please see the LICENSE file.
- For third-party component notices, see LICENSE_THIRD_PARTY.txt and NOTICE.txt.
- GitHub: https://github.com/ZHYX91/docwen
- Contact Author: zhengyx91@hotmail.com
Author: ZhengYX

