How to Convert Word Documents to Markdown
Convert Word documents to Markdown with BulkParse. Preserve useful document structure, review tables and images, and process DOCX files locally or online.

Converting a Word document to Markdown makes its content easier to version, edit in a text editor, or pass into a search pipeline. The useful output is the document's structure: headings, paragraphs, lists, links, and tables.
BulkParse reads DOCX files directly. You do not need to open Word or run LibreOffice for the native conversion. This guide covers a local conversion, the parts of a Word document that need review, and the hosted option in Bulkgrid.
Convert a DOCX file
Install Node.js 20 or newer, then run:
npx @bulkgrid/bulkparse parse handbook.docx -o handbook.mdReplace handbook.docx with your document's path. Choose a new output filename, then open the Markdown in your editor. The first npx invocation may download the package; document conversion itself runs locally without a Bulkgrid API key.
For a quick check without saving an output file, omit the output option:
npx @bulkgrid/bulkparse parse handbook.docxCheck how Word structure becomes Markdown
Word documents contain more than visible text. A paragraph styled as a heading carries information that a line made large and bold may not. Start with a document that uses Word's heading and list styles, then compare the result with the source.
As an illustrative example, a handbook with a section named Getting started and two simple bullet points could become:
# Getting started
Welcome to the project.
- Install the application.
- Open your workspace.This example illustrates the target structure, not a guarantee that every visually similar Word document produces identical Markdown. Custom styles, numbering, text boxes, and floating content can change the result.
BulkParse's DOCX reader supports headings, inherited formatting, simple lists, links, and supported table structures. Some auxiliary content, including referenced headers, footers, and notes, can be extracted without reproducing its exact position on the printed page.
Review tables and document layout
Simple tables may become Markdown tables. More complex tables, including supported merged cells, can use HTML inside the Markdown output. Check that your Markdown renderer supports HTML tables before using the result in a documentation site.
Compare the row and column relationships with the source. A table that contains the right words can still be misleading if a merged heading or nested cell is interpreted incorrectly.
Word's page layout does not map directly to Markdown. Expect differences in fonts, margins, page breaks, headers, footers, and floating-object placement. If the task requires a visually faithful copy, keep the original DOCX or a rendered PDF alongside the extracted content.
Handle embedded images explicitly
If you need supported embedded image assets as well as text, export them during conversion:
npx @bulkgrid/bulkparse parse handbook.docx -o handbook-with-assets.md --export-imagesExporting images saves assets; it does not automatically add image links or an asset section to the Markdown. Embedded images render as alternative text where available, and structured output retains resolved image references. Image pixels are not interpreted automatically by the Office reader.
Use the image support guide when assembling those assets into another publishing system.
Read diagnostics before accepting the result
Export JSON when you need more than the rendered text:
npx @bulkgrid/bulkparse parse handbook.docx --to json -o handbook.jsonThe result includes status, diagnostics, coverage, and document blocks. CLI exit code 2 indicates partial conversion; code 1 indicates failure. Partial output can be useful, but inspect the reported limitations before treating it as a complete replacement for the source.
Strict mode can reject partial results. It cannot prove that every Word feature was reproduced, so include representative source documents in your own checks.
Convert several Word documents
Place the source documents in a directory and keep the output outside that directory:
npx @bulkgrid/bulkparse batch ./word-documents --output ./convertedThe batch command processes files sequentially, continues after individual errors, and does not overwrite existing output files. Preserve the original documents while you review the generated files.
Legacy DOC and macro-enabled DOCM files are also supported by the default build, with format-specific limitations. Macros do not execute during native extraction. Consult the format contracts when working with older documents.
Try it in Bulkgrid
Open the Parse playground to try hosted document conversion, or open your workspace to parse private files. Hosted parsing uploads the file for processing; the local CLI keeps conversion on your machine.
For repeated application workflows, continue with Parse documents with Python or Parse documents with Node.js.