mattn/docx2md: Convert Word Docs to Markdown from the CLI

mattn/docx2md: Convert Word Docs to Markdown^{↗ Smart Converter} from the CLI

Converting Microsoft Word documents into clean, version-control-friendly Markdown remains a persistent friction point for technical teams. Documentation workflows often originate in .docx files—legal contracts, product specs, research notes—only to stall when someone needs that content in a Git repository, static site generator, or developer portal. Manual copy-paste loses formatting. Heavy GUI tools add dependencies. What developers need is a lightweight, scriptable solution that runs anywhere.

mattn/docx2md addresses this directly. Written in Go by Yasuhiro Matsumoto, this open-source CLI tool converts .docx files to Markdown with support for headers, tables, lists, embedded images, and common text styles. With 754 GitHub stars and active maintenance through mid-2026, it offers a pragmatic path for teams automating documentation pipelines. This article examines how mattn/docx2md works, when to use it, and how to integrate it into your workflow.

What is mattn/docx2md?

mattn/docx2md is a command-line utility that transforms Microsoft Word documents (.docx) into Markdown format. It is authored by Yasuhiro Matsumoto, a prolific Japanese developer known for numerous Go-based tools and Vim plugins. The project is hosted at https://github.com/mattn/docx2md and has accumulated 754 stars and 57 forks, indicating modest but steady adoption within the developer community.

The tool is built in Go, which provides native cross-platform compilation and single-binary distribution without runtime dependencies. This architectural choice matters for CI/CD pipelines and containerized environments where installing LibreOffice or Microsoft Word is impractical or prohibited by licensing.

The repository shows active maintenance with its last commit dated July 10, 2026. The license is MIT, as documented in the README, permitting commercial and derivative use with minimal restriction. Notably, the GitHub API response lists the license as "Not specified," which appears to be a metadata inconsistency; the README explicitly states MIT, and this is the authoritative source for licensing terms.

mattn/docx2md occupies a specific niche in the document conversion landscape: it is not a general-purpose document processor like Pandoc, nor a Python^{↗ Bright Coding Blog}-based scripting solution. It is a focused, single-purpose Go tool optimized for one transformation path—.docx to Markdown—making it predictable and easy to embed in automated workflows.

Key Features

The tool's capabilities are documented in its "Supported Styles" section, which enumerates the structural and typographic elements it handles during conversion:

Headers: The tool preserves document hierarchy by converting Word heading styles (Heading 1, Heading 2, etc.) to corresponding Markdown header syntax (#, ##, etc.). This maintains navigational structure for generated tables of contents and semantic document organization.

Hyperlinks: URL references embedded in Word documents are converted to standard Markdown link syntax [text](url), ensuring clickable references survive the transformation.

Indentation: Paragraph indentation levels are mapped to Markdown's indentation conventions, preserving visual hierarchy for nested content without introducing artificial list structures.

Tables: Word table structures convert to Markdown pipe tables. This is particularly valuable for technical documentation containing structured data, comparison matrices, or parameter specifications.

Lists: Both ordered and unordered lists are supported, with nesting levels preserved through appropriate Markdown list syntax.

Text formatting: Bold, italic, and strikethrough formatting convert to **bold**, *italic*, and ~~strikethrough~~ respectively.

Embedded images: The tool extracts images from the .docx archive structure and references them in generated Markdown, though the README does not specify whether images are inlined as base64, saved as external files, or handled through another mechanism.

The Docker^{↗ Bright Coding Blog} support deserves particular mention. The availability of ghcr.io/mattn/docx2md enables ephemeral, reproducible conversions without local Go installation—critical for CI pipelines and ephemeral development environments.

Use Cases

Documentation migration pipelines: Organizations transitioning from Word-based documentation to Markdown-centric systems (MkDocs, Docusaurus, Hugo, GitBook) can script bulk conversions. The CLI interface allows integration with shell scripts, Makefiles, or task runners for batch processing historical document archives.

Legal and compliance workflows: Contracts and specifications often originate as .docx files with tracked changes and comments. Once finalized, converting to Markdown enables storage in version control with meaningful diffs—impossible with binary .docx files. The table and hyperlink support preserves structural elements common in legal documents.

Academic and research publishing: Researchers collaborating across institutions frequently exchange Word documents. Converting accepted manuscripts to Markdown facilitates deposition in preprint servers, institutional repositories, or static-site-based personal academic websites.

CI/CD documentation gates: Teams requiring Markdown source for all published documentation can incorporate mattn/docx2md into pre-commit hooks or CI validation. Contributors submit .docx drafts; the pipeline converts, lints, and publishes automatically.

Containerized microservice documentation: In environments where the host system cannot run traditional office suites, the Docker image provides a hermetic conversion capability. This pattern aligns with [INTERNAL_LINK: containerized-dev-tools] strategies for maintaining consistent tooling across heterogeneous developer machines.

Installation & Setup

The README provides two installation paths: native Go installation and Docker execution.

Go Installation

# Install directly from the Go module proxy
go install github.com/mattn/docx2md@latest

This command leverages Go's module system to fetch, compile, and install the latest release. The @latest version suffix ensures you receive the most recent tagged release. The resulting binary installs to $GOPATH/bin or $HOME/go/bin by default; ensure this directory is in your $PATH.

Prerequisites: Go 1.16 or later (module-aware Go installation). Verify with go version.

Docker Execution

# Run conversion without local installation
docker run -it --rm ghcr.io/mattn/docx2md NewDocument.docx

This command pulls the image from GitHub Container Registry if not present locally, mounts the current directory implicitly (via -v $(pwd):/work if needed for file access), runs the conversion, and removes the container upon completion. The -it flags allocate a TTY for potential interactive output; --rm ensures no container litter accumulates.

For persistent file access, you typically need to bind-mount the host directory:

# Explicit volume mount for file access
docker run -it --rm -v $(pwd):/workdir -w /workdir ghcr.io/mattn/docx2md NewDocument.docx

Note: The README's Docker example assumes the .docx file is accessible within the container context. In practice, volume mounting or piping via stdin may be necessary depending on your execution environment.

Real Code Examples

The README provides two primary usage patterns. These are reproduced exactly with explanatory context.

Basic CLI Conversion

# Convert a Word document to Markdown, output to stdout
$ docx2md NewDocument.docx

This is the fundamental operation. The command accepts a single positional argument—the path to a .docx file—and emits Markdown to standard output. Redirect to a file for persistence:

# Convert and capture output to a file
$ docx2md NewDocument.docx > output.md

The tool follows Unix conventions: read file, write to stdout, let the caller handle redirection. This composes cleanly with pipes (|) for post-processing—feeding into sed, awk, or other text transformers.

Docker-Based Conversion

# Run via Docker without installing Go or the binary locally
$ docker run -it --rm ghcr.io/mattn/docx2md NewDocument.docx

This pattern excels in ephemeral environments. The GitHub Container Registry image (ghcr.io/mattn/docx2md) is maintained alongside the source repository, ensuring version alignment. The --rm flag prevents stale containers; -it provides terminal interactivity for progress indicators or error messages.

Important limitation: The README contains these two examples only. There are no documented flags for output directories, image extraction paths, encoding specifications, or configuration files. Users requiring such control may need to wrap the tool in shell scripts or examine the source directly. This reflects the tool's intentional minimalism rather than a deficiency—scope is deliberately constrained to core conversion.

Advanced Usage & Best Practices

While the README does not document advanced flags, the tool's design suggests several practical patterns:

Batch processing: Combine with find or xargs for directory-scale conversion:

# Convert all .docx files in current directory
find . -name '*.docx' -exec docx2md {} > {}.md \;

Note: This naive approach requires refinement for proper output naming; consider a loop or parallel for production use.

Pre-commit integration: For teams standardizing on Markdown, a pre-commit hook could reject .docx additions or auto-convert them. The single-binary nature simplifies hook configuration.

Image handling verification: Since the README lists "Embeded Image" as supported but does not specify extraction behavior, validate image handling with your specific documents before relying on it in production pipelines. Inspect output directories or run with strace/dtruss to observe file system operations.

Version pinning: For reproducible builds, pin to a specific version rather than @latest:

# Pin to specific version for reproducibility
go install github.com/mattn/docx2md@v1.0.0  # hypothetical version

The README does not enumerate available versions; consult GitHub releases or tags for version identifiers.

Comparison with Alternatives

Pandoc offers broader format coverage and more conversion knobs but requires a Haskell runtime or substantial binary. For teams already using Pandoc, it may suffice; for those seeking a lightweight, Go-ecosystem-aligned tool, mattn/docx2md reduces complexity.

python-docx enables fine-grained control but demands Python environment management and custom development. It suits bespoke extraction logic; mattn/docx2md suits immediate, standardized conversion.

LibreOffice headless handles edge-case formatting but introduces significant container image bloat and potential licensing friction in commercial redistribution.

FAQ

Does mattn/docx2md require Microsoft Word installed? No. It operates directly on the .docx ZIP archive structure, parsing XML internally.

What Markdown flavor does it output? The README does not specify; output appears to follow CommonMark-compatible syntax based on documented features.

Can it convert Markdown^{↗ Smart Converter} back to .docx? No. This is a one-directional tool: .docx → Markdown only.

How are images handled during conversion? The README states "Embeded Image" is supported but does not detail extraction paths or encoding. Verify behavior with your documents.

Is commercial use permitted? Yes. The README specifies MIT license, allowing commercial use with attribution.

What Go version is required? The README does not specify minimum Go version; go install with module support (Go 1.16+) is standard practice.

Is the project actively maintained? The last commit is dated July 10, 2026, indicating recent activity at time of documentation.

Conclusion

mattn/docx2md fills a well-defined gap: converting Microsoft Word documents to Markdown without heavy dependencies or complex configuration. Its Go implementation yields portable binaries; its Docker image enables ephemeral, reproducible execution. The 754-star repository reflects utility for developers who value composable, scriptable tools over monolithic office suites.

This tool best serves teams migrating documentation to Markdown-centric workflows, automating conversion in CI pipelines, or operating in constrained environments where traditional office software is unavailable. It does not replace full-featured converters like Pandoc for multi-format needs, nor does it offer the granular control of programmatic libraries. For focused .docx → Markdown conversion, it is a pragmatic, credible choice.

Explore the repository, review the source, and evaluate it against your specific document structures: https://github.com/mattn/docx2md.