md2docx-cli

md2docx-cli

A powerful command-line tool for converting Markdown files to DOCX files using Pandoc. It simplifies the Pandoc workflow by providing predefined options, template management, and cross-platform support.

Features

• Pandoc Wrapper: Provides a convenient CLI interface for Pandoc with optimized default options.
• Template Management: Manage multiple DOCX templates via optional npm packages.
• WINE Integration: Supports WINE bottle environments on Linux/macOS for Windows-specific workflows.
• Cross-Platform Filters: Includes Lua filters for extended functionality (e.g., xlsx, Mermaid diagrams).
• Resource Path Management: Automatically configures Pandoc resource paths for assets and styles.
• Logging Support: Optional log file output with configurable stream filtering.

Prerequisites

• Pandoc version 3.0+ (with Lua 5.4 scripting engine)
• Node.js 22.14.0+ and npm

Installation

Install

Install the package globally using npm:

npm install -g md2docx-cli

Post-Installation

Upon installation, md2docx automatically performs the following setup tasks:

• Mounts Lua scripts to Pandoc's lib, filters, and custom directories.
• Installs default configuration files.
• Mounts reference document templates.
• Creates a metadata file containing CLI tool paths (e.g., xlsx2md-cli, mmap2md-cli, mermaid-cli).

Manual Mount

If you need to manually mount components or re-run the setup:

md2docx-mount [options]

Options

Option	Description
-v, --verbose	Show detailed log output

Basic Usage

The md2docx command utilizes a set of predefined Pandoc options and scripts to perform DOCX conversion.

Command Syntax

md2docx [options] [--- [CONVERTER ARGUMENTS]]

Options

Option	Description	Default	Env
-V, --version	Output the version number.	-	-
-c, --converter-path <PATH>	Specify the path for the converter.	"pandoc"	MD2DOCX_CONVERTER_PATH
--log-file <FILE>	Write log messages to a specified file.	-	-
--log-filter <STREAM>	Filter the log file messages by STREAM.	"both"	-
-h, --help	Display help for the command.	-	-

Arguments

Argument	Description
---	Separator. All arguments after this are passed directly to Pandoc.
CONVERTER ARGUMENTS	Input files and additional Pandoc options.

WINE-Specific Options

Available when running on non-Windows platforms.

Option	Description	Default	Env
--bottle <NAME>	Specify a specific WINE bottle. When used, file paths in arguments are automatically converted from Windows to Unix format.	-	-
-w, --wine-path <PATH>	Specify the path for WINE.	"wine"	MD2DOCX_WINE_PATH

Examples

Basic Markdown to DOCX Conversion

md2docx --- input.md -o output.docx

Convert XLSX to DOCX using the xlsx2md Filter

md2docx --- -f xlsx.lua -o test.docx test.xlsx

Using Reference Document Options

md2docx --- --reference-doc=template.docx --toc --toc-depth 3 input.md -o output.docx

Using WINE Bottle

md2docx --bottle my-bottle --- input.md -o output.docx

Advanced Features

Environment Variables

Variable	Description	Default
MD2DOCX_CONVERTER_PATH	Path to the Pandoc executable.	pandoc
MD2DOCX_CONVERTER_DATA_DIR	Custom Pandoc user data directory.	Auto-detected
MD2DOCX_CONVERTER_RESOURCE_PATH	Additional resource path for Pandoc.	None
MD2DOCX_WINE_PATH	Path to the WINE executable.	wine
MD2DOCX_NPM_PATH	Path to the NPM executable.	npm
MD2DOCX_FORCE_INSTALL	Force installation during post-install.	true
MD2DOCX_FORCE_UNINSTALL	Force uninstallation during cleanup.	false

Resource Path Configuration

Use the MD2DOCX_CONVERTER_RESOURCE_PATH environment variable to specify additional resource paths for Pandoc. This automatically adds the --resource-path option to the Pandoc command.

export MD2DOCX_CONVERTER_RESOURCE_PATH=/path/to/resources
md2docx --- input.md -o output.docx

Logging

Log File Output

Use --log-file to write logs to a specific file:

md2docx --log-file ./conversion.log --- input.md -o output.docx

Log Stream Filtering

Filter which streams are captured in the log file:

# Log both stdout and stderr (default)
md2docx --log-file ./log.txt --log-filter both --- input.md -o output.docx

# Log only stdout
md2docx --log-file ./log.txt --log-filter stdout --- input.md -o output.docx

# Log only stderr
md2docx --log-file ./log.txt --log-filter stderr --- input.md -o output.docx

WINE Integration

For scenarios where md2docx needs to be used within a WINE bottle environment, you can create a script link to call the md2docx tool installed on the host environment from within the WINE bottle.

Link Management

The md2docx-link command manages the md2docx link within WINE bottles.

md2docx-link [options] <BOTTLE>

Options & Arguments

Parameter	Type	Description	Default	Env
BOTTLE	Argument	Specify a WINE bottle.	-	-
-V, --version	Option	Output the version number.	-	-
-w, --wine-path <PATH>	Option	Specify the path for WINE.	"wine"	MD2DOCX_WINE_PATH
-u, --unlink	Option	Remove the link.	-	-
-t, --target <PATH>	Option	Specify the link PATH.	"C:\\windows\\system32\\md2docx.exe"	-
-h, --help	Option	Display help for the command.	-	-

Create a Link

md2docx-link my-bottle

Remove a Link

md2docx-link --unlink my-bottle

Custom Target Path

md2docx-link --target "C:\\Program Files\\md2docx\\md2docx.exe" my-bottle

Template Management

Pandoc uses reference documents as templates to format DOCX outputs. To manage multiple templates, md2docx provides an npm-based solution. In this context, a package used for packaging templates is referred to as an optional package. These packages can be managed using the md2docx-pm command.

Users first install the optional package using npm, and then manage the activation of templates by mounting or unmounting them with md2docx-pm.

Command Syntax

md2docx-pm [options] [command]

Global Options

Option	Description	Default	Env
-V, --version	Output the version number.	-	-
-c, --converter-path <PATH>	Specify the path for the converter.	"pandoc"	MD2DOCX_CONVERTER_PATH
-n, --npm-path <PATH>	Specify the path for NPM.	"npm"	MD2DOCX_NPM_PATH
-v, --verbose	Show the details log.	-	-
-h, --help	Display help for the command.	-	-

Commands

Command	Description
list | ls	List all optional packages.
mount [options] [packages...]	Mount the specified optional packages, or all if none are specified.
unmount [options] [packages...]	Unmount the specified optional packages, or all if none are specified.
clean [options]	Remove all unmanaged template files.
repair [options] [packages...]	Repair the specified optional packages, or all if none are specified.
help [command]	Display help for a specific command.

Sub-command Options

Command	Option	Description
mount | unmount | repair	-g, --global	Operate in global scope.
clean	--backup <FOLDER>	Move unmanaged template files to the specified folder.

Package Status

• mounted: Template files are properly linked/copied to the Pandoc user data directory.
• unmounted: Template files exist in the package but are not installed.
• corrupted: Template files exist but content differs from the package.
• conflicted: Multiple packages provide the same template file.

Template Package Commands

List all available packages

md2docx-pm list

Mount specific packages

md2docx-pm mount template-package-name1 template-package-name2

Mount all packages

md2docx-pm mount

Unmount specific packages

md2docx-pm unmount package-name1

Repair corrupted packages

md2docx-pm repair package-name

Clean unmanaged templates

md2docx-pm clean

Clean with backup

md2docx-pm clean --backup ./template-backup

Global scope operations

md2docx-pm mount -g template-package-name

Creating a Template Package

To create a custom template package:

• Create a package with the following package.json configuration:

  {
    "name": "my-custom-template",
    "version": "1.0.0",
    "config": {
      "md2docx_package_type": "template"
    }
  }
  

• Add template files to a templates folder:

  • .docx files for reference documents.
  • .md files for metadata templates.

• Install the package globally or locally:

  npm install -g my-custom-template
  

• Mount the package:

  md2docx-pm mount -g my-custom-template
  

Maintenance

Unmount

To remove all installed components without uninstalling the package:

md2docx-unmount [options]

Options

Option	Description
-v, --verbose	Show detailed log output

Uninstall

To completely remove md2docx and clean up the Pandoc user data folder:

• Run md2docx-unmount to clean the directory:

  md2docx-unmount
  

• Uninstall the npm package:

  npm uninstall -g md2docx-cli
  

Repair

If the md2docx files within the Pandoc user data folder become corrupted:

• Attempt to restore files to their original state:

  md2docx-mount
  

• For specific template packages:

  md2docx-pm repair package-name
  

Exit Codes

Code	Description
0	Success.
-400	Configuration error (e.g., package info not found).
-500	Execution error (e.g., Pandoc execution failed, process aborted).

License

MIT.