How to export markdown to microsoft word .docx
- Step 1Get the spec into one Markdown file — If the spec is split across files, combine the sections first with md-merger so the whole deliverable converts in a single pass — md-to-docx takes one file at a time.
- Step 2Tidy the structure (optional but recommended) — Run md-prettifier to normalize spacing and md-heading-shifter if the outline starts at the wrong level — Word's ToC depends on a clean H1→H6 hierarchy.
- Step 3Paste or upload the Markdown — Use the Paste tab for a quick snippet or the Upload tab for a
.md/.markdown/.mdx/.txtfile. Everything is read locally in the browser. - Step 4Click Run to build the document — marked tokenizes the source and docx.js assembles a native .docx — headings, tables, code, lists, and links are mapped in one fixed pass with no prompts.
- Step 5Download the .docx — The file is named after your source with the extension swapped (
spec.md→spec.docx). Open it in Word to confirm the heading outline. - Step 6Attach the client template — In Word, attach the client or PMO template (Design → Themes, or attach a document template). Because headings use built-in style names, the whole spec restyles at once.
What survives the conversion
Every Markdown construct mapped to what md-to-docx actually writes into the .docx. Built with marked (tokenizer) + docx.js (document builder), both running in your browser. There are no conversion options — the mapping below is fixed.
| Markdown | In the .docx | Notes |
|---|---|---|
# H1 … ###### H6 | Word's built-in Heading 1–6 styles | Depths past 6 (#######) clamp to Heading 6 |
**bold**, *italic*, ~~strike~~ | Bold, italic, strikethrough runs | Combine freely in body paragraphs and headings |
inline code | Courier New run at 9pt | No background shading or colour — just the monospace font |
Fenced ``` ``` blocks | One Courier New 9pt paragraph per line | No syntax highlighting (Word has no native code highlighter) |
> blockquote | Italic paragraph indented 0.5" (grey 666666) | Indent is fixed at 720 twips |
[text](url) | Blue (0563C1) underlined hyperlink | Real clickable link, not just styled text |
GFM | table | | Native Word table, bold header row, 1pt borders | Columns share a 9000-twip width evenly; cells are plain text |
- item / 1. item | Word bullet / decimal-numbered list | Top level only — see nesting note below |
--- (horizontal rule) | Paragraph with a bottom border | Acts as a thin grey divider line |
 | The alt text as plain text | No image is embedded — see the images edge case |
Tier limits for the Markdown family
md-to-docx counts as a Markdown-family tool. Two independent limits apply: total file size in bytes AND a character count (charLimit). The converter accepts a single file per run (no batch).
| Plan | Max file size | Max characters | Files per run |
|---|---|---|---|
| Free | 1 MB | 500,000 | 1 |
| Pro | 10 MB | 5,000,000 | 10 (family) — md-to-docx still takes 1 at a time |
| Pro-media | 50 MB | 20,000,000 | 50 (family) — md-to-docx still takes 1 at a time |
| Developer | 500 MB | Unlimited | Unlimited (family) — md-to-docx still takes 1 at a time |
Spec-deliverable pitfalls and the fix
Common Markdown-to-Word surprises for delivery teams, and how to handle each before sending the .docx to a client.
| Symptom in Word | Cause | Fix |
|---|---|---|
A --- divider and stray key/value text at the top | YAML frontmatter is treated as content | Strip frontmatter before converting |
| Architecture diagram missing | Images aren't embedded | Insert pictures in Word after conversion |
| Sub-requirements not indented as sub-levels | Nested lists fold into the parent item | Flatten to one level or apply Word's multilevel list |
| Code sample isn't colour-highlighted | Word has no native code highlighting | Expected — characters are exact; use a PDF export for colour |
Cookbook
Realistic before/after fragments from enterprise specs and statements of work. The right column shows what lands in the .docx.
Requirement matrix becomes a real Word table
A GFM table of requirements converts to a native bordered Word table with a bold header — reviewers can sort and comment on it like any Word table.
Markdown source: | ID | Requirement | Priority | |------|------------------------|----------| | R-01 | SSO via SAML 2.0 | Must | | R-02 | Audit log export (CSV) | Should | In the .docx: [ Word table, 3 cols x 3 rows, 1pt borders ] Header row bold: ID | Requirement | Priority Body cells plain text.
Section outline drives the Navigation Pane
Heading levels map to Word's built-in styles so the client's reviewer can jump around with the Navigation Pane and you can insert a live ToC.
Markdown:
# Statement of Work
## 1. Scope
### 1.1 In Scope
### 1.2 Out of Scope
## 2. Timeline
In Word:
Heading 1: Statement of Work
Heading 2: 1. Scope
Heading 3: 1.1 In Scope
Heading 3: 1.2 Out of Scope
Heading 2: 2. Timeline
(References -> Table of Contents picks these up.)Inline code and config snippets
Endpoint names and config keys keep a monospace font; fenced blocks stay line-accurate for copy-paste fidelity.
Markdown: Call `POST /v1/provision` with: ``` region = eu-west-1 retries = 3 ``` In the .docx: Call POST /v1/provision with: <- 'POST /v1/provision' in Courier New region = eu-west-1 <- Courier New 9pt retries = 3 <- Courier New 9pt
Clickable links survive
Reference URLs to standards or ticket trackers stay clickable for the client.
Markdown:
See the [security baseline](https://example.com/baseline) doc.
In the .docx:
See the security baseline doc.
^^^^^^^^^^^^^^^^^ blue, underlined, clickable hyperlinkMerge multi-file specs first
md-to-docx is one-file-in, so assemble multi-section deliverables before converting.
Workflow:
1. md-merger: 00-intro.md + 01-scope.md + 02-arch.md
-> deliverable.md
2. md-to-docx: deliverable.md -> deliverable.docx
3. Word: attach client template, insert ToCEdge cases and what actually happens
YAML frontmatter is treated as document content
Watch outA --- delimited YAML frontmatter block at the top of the file is not stripped for this converter — marked sees the opening --- as a horizontal rule and the key/value lines as a paragraph, so your metadata can appear as visible text plus a divider line in the Word output. Remove frontmatter before converting, or build/clean it with md-frontmatter-builder and delete it before export.
Images are not embedded in the .docx
By design does not place a picture in the Word file. An inline image renders its alt text as plain text; a standalone image line renders as text too. No binary image data is fetched or embedded. After converting, insert images in Word via Insert → Pictures, or export your figures separately and add them where the alt text appears.
Deeply nested lists don't get separate Word sub-levels
By designThe converter emits Word list paragraphs for top-level items only — bullets for -/* lists, decimal numbers for 1. lists. A nested list under an item is folded into that item's text run rather than written as an indented Word sub-level. The bullet/number markers still read clearly, but you won't get true multi-level outline numbering automatically. If you need precise sub-level numbering, flatten the list to one level in Markdown first, or apply Word's list styles after opening the file.
Bold/links inside a table cell render as plain text
Preserved as textGFM tables convert to real Word tables with a bold header row and 1pt borders, but cell contents are written as plain text. **bold**, [links](url), and ` code ` inside a cell keep their literal Markdown characters rather than becoming formatted runs. Keep table cells to plain values; put rich formatting in the surrounding body paragraphs, or style the cells in Word afterward.
Code blocks keep their text but lose colour
PreservedFenced code blocks survive: each line becomes a Courier New 9pt paragraph, so indentation and characters are exact. There is no syntax highlighting and no shaded code background — Word has no native code-highlighting feature. The fence's language hint (``` python ```) is not rendered as a label. For a syntax-coloured result, convert to HTML or PDF with a sibling tool instead.
Only one file converts per run
By designmd-to-docx takes a single Markdown source — paste it or upload one .md/.markdown/.mdx/.txt file. It does not merge multiple files into one Word document. To assemble several Markdown sections into one document, combine them first with md-merger, then run the merged file through md-to-docx.
Heading depth past level 6
Clamped to Heading 6Markdown allows ####### (seven hashes) but Word only has Heading 1 through Heading 6. Any heading deeper than six maps to Heading 6 rather than being dropped. If your document relies on a seventh level, restructure the outline or shift it up with md-heading-shifter before converting so the hierarchy reads correctly in Word's Navigation Pane.
Task-list checkboxes disappear
Watch outGFM task items (- [ ] todo, - [x] done) convert to ordinary Word bullets — the [ ]/[x] checkbox marker is dropped and the checked/unchecked state is not represented. The item text is preserved. If the checkbox state matters, spell it out in the text (for example prefix with DONE: / TODO:) before converting.
Empty or whitespace-only input
ExpectedIf the source has no content, the converter still produces a valid one-paragraph .docx rather than erroring — you get an openable but empty Word file. Confirm you pasted or uploaded the right source if the result looks blank.
Frequently asked questions
Will Word's Navigation Pane and outline view work?
Yes. Headings map to Word's built-in Heading 1–6 styles, so the Navigation Pane, outline view, and an inserted Table of Contents all pick them up automatically. After conversion you can add a ToC via References → Table of Contents and it will read the heading levels directly.
Do my Markdown tables become real Word tables?
Yes — GFM pipe tables (| col | col |) become native Word table objects with a bold header row and 1pt borders, not images or tab-separated text. Columns share the page width evenly. Cell contents are written as plain text, so put any bold/links in surrounding paragraphs. If your source tables are misaligned, fix them with md-table-repair first.
How are code blocks rendered?
Fenced code blocks become Courier New 9pt paragraphs, one per line, preserving exact characters and indentation. There is no syntax-colour highlighting and no shaded background — Word doesn't highlight code natively — and the language hint after the opening fence is not shown as a label.
Are numbered and bulleted lists preserved?
Top-level lists are: -/* become Word bullets and 1. lists become decimal-numbered Word lists. Nested sub-lists are folded into the parent item's text rather than getting their own indented Word sub-level. For deep multi-level numbering, flatten the list in Markdown or apply Word's multilevel list style after conversion.
Why didn't my images show up?
Images are not embedded.  renders as its alt text only; no picture is fetched or placed in the .docx. Insert images in Word after conversion (Insert → Pictures) where the alt text appears, or keep image-heavy documents in a PDF export instead.
Do links stay clickable in Word?
Yes. [text](https://…) becomes a real Word hyperlink styled blue (0563C1) and underlined, clickable in Word, LibreOffice, and Google Docs. Reference-style links resolve to the same hyperlink. To audit links before converting, run md-link-validator.
Can I apply my own corporate or template styles afterward?
Yes. Because headings use Word's standard built-in style names (Heading 1, Heading 2, …) rather than ad-hoc formatting, attaching a company template or changing the theme restyles the whole document at once. Open the .docx, then Design → Themes or attach your template via the Developer → Document Template dialog.
What formatting options can I set before converting?
None — md-to-docx has no options panel. It uses a fixed, opinionated mapping (built-in heading styles, Courier New for code, blue underlined links, bordered tables). To change structure before converting, use the editing tools first: md-prettifier to normalize spacing, md-heading-shifter to fix the outline, or md-table-repair to align tables.
What is the output file named?
The downloaded Word file reuses the source name with the extension swapped to .docx — proposal.md becomes proposal.docx. If you pasted text instead of uploading a file, a default name is used. The document's internal title metadata is set from the filename, and the creator is recorded as "JAD Markdown".
Does the .docx open in LibreOffice and Google Docs?
Yes. docx.js writes a standards-compliant Office Open XML (.docx) file, so it opens in Microsoft Word, LibreOffice Writer, and Google Docs (via upload/import). Built-in heading styles and the table grid carry across all three; minor spacing differences between apps are normal.
Does my document get uploaded to a server?
No. The whole conversion runs in your browser — marked tokenizes the Markdown and docx.js assembles the .docx locally. The file content never leaves your machine, so confidential drafts stay private. The only thing recorded server-side for signed-in users is a usage counter (that a conversion ran, not its contents).
Is there an API or command-line way to run this?
Not for the .docx output. The public API and MCP run the text-output Markdown tools server-side, but binary-output tools (md-to-docx, the md-to-pdf converters, md-splitter) return a 400 that points back to the web tool — Word generation only happens in the browser. For an automatable, text-only export use md-to-html or md-to-github-html and convert HTML to Word in your pipeline.
Privacy first
All Markdown processing runs locally in your browser using JavaScript. No file is ever uploaded to JAD Apps servers — only metadata counters are saved for signed-in dashboard stats.