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:

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

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

2. Add template files to a templates folder:

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

3. Install the package globally or locally:

   npm install -g my-custom-template

4. 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:

1. Run md2docx-unmount to clean the directory:

   md2docx-unmount

2. Uninstall the npm package:

   npm uninstall -g md2docx-cli

Repair

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

1. Attempt to restore files to their original state:

   md2docx-mount

2. 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.