Word to Markdown Converter

Word, Google Docs, Notion → Markdown — moving prose into version control

Markdown is the writing format of every serious documentation system: GitHub README files, MDX-based docs sites, Astro and Next.js content pipelines, static site generators, Notion exports, Obsidian vaults, and AI training datasets. Yet most authoring still happens in Word, Google Docs, or Notion — tools where the source is a binary blob you cannot diff. The bridge is conversion: paste rich text, get Markdown. This guide walks through the Markdown spec landscape (yes, there is more than one), the lossy transitions that bite every team, and the practical moves that keep your converted content rendering correctly across GitHub, Notion, Obsidian, and your static site generator.

Markdown is not one spec — it is six

This converter outputs GitHub Flavored Markdown, the safest target for portability. It renders correctly in GitHub, GitLab, Astro, Next.js, Eleventy, Hugo, MkDocs, Docusaurus, and most of Notion's import.

What survives the conversion — and what does not

The "fake heading" problem — why headings disappear

The single biggest source of "the headings didn't come through" complaints is that the source document used direct formatting (font size 24, bold) instead of paragraph styles (Heading 1, Heading 2). Browsers expose only what HTML semantics encode. Direct formatting becomes <span style="font-size: 24pt; font-weight: bold">…</span>, which is just bold text — not an <h1>.

The fix is structural, not cosmetic:

• Word: Home → Styles → apply Heading 1 / Heading 2 / Heading 3 from the gallery.
• Google Docs: Format → Paragraph styles → Heading 1 / Heading 2.
• Notion: the slash-menu styles ("/h1", "/h2") already create real headings.
• Pages, LibreOffice, Quip: all expose paragraph-style menus.

Image handling — the trickiest part

Pasted images can come in three forms, each with different conversion behavior:

1. External URL (https://example.com/img.png) — survives intact. The Markdown image points to the original URL.
2. Base64 data URI (data:image/png;base64,…) — survives, but inflates the file size by ~33% and embeds the image in the Markdown. Useful for self-contained docs; bad for git.
3. Browser blob URL (blob:https://docs.google.com/…) — only works in the browser session that created it. After conversion, these images break unless you save them locally first.

The pragmatic workflow for Google Docs: download the document as .html (which packages images) and paste from there, or use Docs' "Download as Markdown" if it has been enabled in your workspace.

Table conversion — the two formats and their limits

The output uses GFM pipe tables:

| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| cell     | cell     | cell     |

Limitations to be aware of:

• No row spans, no col spans. Word/Google tables with merged cells degrade.
• No nested block content (lists, paragraphs, code blocks) inside cells. Multi-line content collapses.
• No table captions in CommonMark / GFM. Pandoc Markdown supports them; for portability, just precede the table with a paragraph.

Common Word-to-Markdown mistakes

• Pasting from a PDF reader. PDFs are visually-laid-out, not semantically-tagged. The "headings" you see are usually just larger fonts. Use a Word document or HTML source.
• Forgetting that smart quotes break code blocks. Word auto-replaces straight quotes with curly quotes; curly quotes inside ```code``` blocks break syntax highlighters. Run a final find-and-replace.
• Em-dashes mangling pre-formatted text. Word also rewrites -- to —. Add it to the same find-and-replace pass.
• Trusting "convert to Markdown" extensions blindly. Many produce <br> tags inside paragraphs because the source had soft line-breaks. Strip them or run the output through a Markdown formatter.
• Mixing line-ending styles. Pasting from Windows Word adds \r\n. Most renderers tolerate it; some build tools (older Eleventy versions) trip up. Normalize to \n on save.
• Forgetting that Markdown is whitespace-sensitive. A paragraph break is two newlines; a list item needs the right indentation; nested code requires four spaces. Word produces consistent line breaks but unpredictable indentation.

Round-tripping — Markdown → Word → Markdown

Sometimes you need to send a Markdown file to a non-technical stakeholder, get edits in Word, and convert back. Pandoc is the gold-standard tool for round-tripping:

# Markdown to Word
pandoc input.md -o output.docx

# Word back to Markdown
pandoc input.docx -t gfm -o output.md

Round-tripping is lossy: Word adds direct formatting, table styling, and font specifications that translate back imperfectly. Always diff before merging.

The build-time conversion pipeline

For doc teams that author in Notion or Confluence and ship to a static site, automation beats manual conversion:

• Notion → Markdown: the notion-to-md npm package, or Notion's official Markdown export.
• Confluence → Markdown: confluence-to-markdown CLI, or Atlassian's "Export to HTML" + Pandoc.
• Google Docs → Markdown: the official "Export to Markdown" Workspace add-on (2024+) or docs-to-markdown Apps Script.
• Word → Markdown: Pandoc remains the canonical answer.