How to Convert Word Documents to Markdown (DOCX to MD)

Markdown is the lingua franca of documentation sites, README files, static-site generators, and note-taking apps like Obsidian. Word, meanwhile, is where most of the world's drafts, reports, and meeting notes still live. The bridge between them — converting Word documents to Markdown — is one of the most common format migrations in technical writing. Done well, you get clean, semantic Markdown that re-renders perfectly. Done poorly, you get a sea of inline HTML, broken tables, and escaped punctuation. This guide covers the practical workflows for going from .docx to .md and how to clean up the result.

Why Convert Word Documents to Markdown

Word stores documents as a deep pile of styled XML, with explicit runs, paragraph styles, and theme colors. Markdown, by contrast, is a plain-text description of structure that any renderer can interpret. Converting between them gives you several concrete benefits:

• Portability. Plain text works in every editor, terminal, and version-control system. You can diff a Markdown file in Git; a .docx is an opaque binary-ish archive.
• Future-proofing. Markdown authored today will render in fifteen years with no conversion layer. Word files depend on Microsoft's format continuity.
• Publishing pipelines. Docs sites (Docusaurus, MkDocs, Astro, Hugo) consume Markdown directly. Feeding them Word files requires an export step anyway.
• AI and search. LLMs and search indexers read plain text far more cleanly than OOXML.
• Editing speed. Once you know the syntax, writing Markdown is faster than reaching for the mouse every few seconds.

The catch is fidelity: not every Word feature maps cleanly to Markdown, which is why the quality of the converter matters as much as the decision to convert.

How to Convert DOCX to Markdown Online

For a one-off document, open the Word to Markdown converter and choose a .docx file. The conversion runs in your browser. Review and edit the Markdown, then download the .md file or a ZIP containing the document and its extracted images. Files up to 10 MB are supported; legacy .doc, encrypted documents, and exact page layout are not.

The converter uses Word heading styles and lists to recover structure. Simple tables become GFM tables; merged tables remain sanitized HTML. Embedded PNG, JPEG, GIF and WebP images are extracted to an images/ directory. Keep that directory next to the Markdown file after unzipping. Review conversion notes for unsupported image formats or document elements before replacing your source document.

What a Good DOCX to Markdown Output Looks Like

A faithful export should turn Word's semantic styles into the corresponding Markdown syntax rather than leaving them as inline HTML:

• Heading 1 → #, Heading 2 → ##, and so on.
• List Bullet and List Number → - and 1.
• Bold and italic runs → **bold** and *italic*.
• Hyperlinks → [text](url).
• Tables → GFM pipe tables, not <table> markup.

If your converter emits lots of raw <span style="..."> tags, it is preserving appearance at the expense of semantics — fine for a quick preview, bad for long-term maintenance. For a round-trip workflow (Markdown back to Word), you can later re-export through Markdown to Word; for publishing to the web, you might instead route through Markdown to HTML.

A quick verification checklist:

• All headings map to #, ##, ###
• Lists render as - or 1., not as <ul>/<ol>
• Tables are GFM pipe tables
• Links are inline [text](url) references
• No leftover inline styling spans

Convert Word to Markdown with Pandoc

When you have many documents, or when you need repeatable, scriptable conversions, Pandoc is the standard tool. It is a free command-line document converter that reads .docx and emits Markdown (among dozens of other formats).

Install Pandoc and Convert a Single File

On macOS install with Homebrew, on Windows with Chocolatey, or use your Linux distro's package manager:

# macOS
brew install pandoc

# Convert one document
pandoc report.docx -f docx -t gfm -o report.md

The -f docx flag declares the input format and -t gfm asks for GitHub Flavored Markdown output, which handles tables, strikethrough, and task lists. Drop the -t flag and Pandoc defaults to its own markdown flavor, which supports more extensions but is less widely supported by renderers.

Batch Convert DOCX to Markdown

A short shell loop converts an entire folder, which is invaluable when migrating a wiki or an internal docs site:

for f in *.docx; do
  pandoc "$f" -f docx -t gfm -o "${f%.docx}.md"
done

Two flags worth knowing for cleaner output:

• --wrap=none disables hard line wrapping, so paragraphs stay on a single line.
• --extract-media=./media writes embedded images to a folder and rewrites the Markdown to point at them.

A useful Pandoc invocation for a documentation migration:

pandoc report.docx -f docx -t gfm \
  --wrap=none --extract-media=./media -o report.md

How Word Styles Map to Markdown Syntax

The quality of any conversion depends on how the source document uses Word's styles. A document built on the proper Heading and List styles converts almost perfectly; one where the author manually made text "big and bold" to fake a heading converts terribly, because the converter has no semantic signal to work with.

If a conversion looks noisy, the fix is usually upstream: open the original Word file, apply real Heading styles to the headings, and re-run the export.

Tip: before batch-converting a whole archive, fix the styles in one representative document, convert it, and confirm the output. Once the pattern is right, the rest of the archive will follow.

Handle Tables and Images When Converting Word to Markdown

Tables

GFM pipe tables require a header row and a delimiter row, and they do not support cell merging or column spans. When Word tables use those features, converters have to improvise: Pandoc will split a merged cell across multiple rows, which can look messy. If a table is structurally complex, the pragmatic options are:

1. Simplify the table in Word first (unmerge cells, flatten headers).
2. Keep the table as an HTML block (<table>…</table>) inside the Markdown — most renderers will pass it through.
3. Replace the table with a list if the data is really a key/value set.

Images

Word embeds images inside the .docx archive. A good converter extracts them to a folder and rewrites the Markdown to reference those files:

![Architecture diagram](./media/image1.png)

Things to watch for:

• Relative paths. Decide whether your publish pipeline expects ./media/, /assets/, or absolute URLs, and adjust the paths accordingly.
• Captions and alt text. Word image captions rarely survive; add descriptive alt text in Markdown for accessibility.
• Floating images and text wrap — Markdown has no layout model, so floating images become plain inline images.
• Image-heavy documents. If your file is essentially a slide deck, Markdown may not be the right target; consider exporting directly to PDF instead.

After conversion, run a quick find-and-replace pass to normalize heading levels, strip empty links, and tidy list markers. A clean source document plus a good converter gets you 95% of the way there; the last 5% is the manual polish that makes the Markdown feel hand-written.

Conclusion: Choose Your Word to Markdown Workflow

For a single document, a browser-based converter is the quickest route; for a folder or a whole wiki, Pandoc with the gfm output and --extract-media flags is the workhorse. Either way, the secret to clean output is clean source: apply real Heading and List styles in Word before you export, simplify tables, and add alt text to images. Once your content lives in Markdown, you can repurpose it anywhere — re-export to Word with Markdown to Word, publish to the web with Markdown to HTML, or extract text into structured notes with the text to Markdown tool. Browse the blog for more format-conversion guides.