Markdown for Word: keep text and styles apart
Keep Markdown as plain text when its characters are the deliverable, and convert it when Word formatting is the deliverable. Using Markdown with Word involves three workflows: editing source text, importing formatted content, and exporting a styled Word document.
Choose a Markdown workflow for Word
Choose plain text for source editing, parsed content for Word delivery, and a structural exporter for Word-to-Markdown work.
| What you have | How to identify the requirement | Route |
|---|---|---|
| Markdown source that must remain editable as source | Paste a heading and a table row into a text editor. If the hash and pipes must remain editable characters, preserve the source | Keep a plain text master and use a source-preserving editing workflow |
| Markdown that colleagues need to edit as a Word document | Inspect the intended Word handoff: the title must use a heading style and each table value must occupy a cell | Parse Markdown into DOCX, or use a documented Markdown import command |
| A Word document being prepared for Markdown publication | Select a heading and a table entry in the Word source. A paragraph style and native cells identify the structural export route | Export the document's structure and inspect how those elements map to Markdown |
Markdown for Word is also the name of an anouri add-in. Its listing describes Markdown import and export. Writage documents opening and editing Markdown inside Word. These are added conversion features with their own commands. The add-ins were not executed for this guide. 34
A source editor should retain the punctuation you intend to publish. A converter may remove that punctuation and create document structure. An exporter may introduce different punctuation to represent the Word content.
Keep source text when the punctuation matters
Use a text-preserving workflow when punctuation, spacing, and Markdown markers are the document.
Copy the Markdown source as plain text, edit the characters, and save a text copy. In desktop Word for Windows, use File > Save As > Plain Text and select UTF-8 in the encoding dialog. This is a text-file workflow, with no promise to turn Word styling into Markdown syntax. Renaming a Word document does not change the representation stored inside it. 2
Text-only paste is useful for bringing literal characters into Word without carrying over the source application's formatting. It also discards the structure of a rendered table. Use it for the source-editing case, where the pipes and separator row are intentional text. Microsoft's paste documentation describes tables becoming paragraphs when Keep Text Only is selected. 1
We constructed a Word file whose paragraphs contained a hash heading, paired asterisks, a quote marker, and pipe-table lines as ordinary characters. Pandoc escaped those markers when exporting the file. 12
Output from our literal-marker Word sample, unedited:
\# Review
Ship \*\*today\*\*.
\> Internal only.
The backslashes preserve the literal meaning of the Word paragraphs when the result is rendered as Markdown. They also change the source characters. That export is unsuitable as a way to recover the original active Markdown syntax from a Word wrapper. Keep the original text master if its source is the deliverable. 612
MarkItDown left the leading hash and quotation marker active in the same constructed Word file, while escaping the asterisks. Rendering its export produced a heading and a quotation that were absent from the Word structure. This reproduces the leading-hash failure shape described in an upstream issue, using our own fixture and installed version. 1112
| Symptom after export | What happened in our sample | Appropriate response |
|---|---|---|
| Backslashes appear before the markers | The exporter protected literal Word text from Markdown interpretation | Return to the source master if you wanted active Markdown |
| Ordinary Word text becomes a heading or quotation | Markers remained active and acquired meaning during rendering | Use text preservation when the characters themselves must survive |
Render Markdown before importing formatted content
Parse Markdown before handing Word a document that needs headings or table cells.
With Pandoc, the GFM reader handles pipe tables. This command generated a DOCX with a heading style and a native table in our small import sample. It establishes document structure, without establishing pagination or the appearance in a Word client. 512
pandoc -f gfm input.md -o output.docx
Our local renderer in CommonMark mode left the pipe table as a paragraph, while Pandoc's GFM reader emitted a table. The GFM specification defines pipe tables as an extension. Use a Markdown file viewer configured for the dialect you will convert. If the intended table still appears as pipe-separated text, the preview has not parsed it as a table. 6712
Output from Pandoc's GFM rendering of our import sample, unedited:
<table>
<thead>
<tr>
<th>Task</th>
<th>Owner</th>
</tr>
</thead>
Output from markdown-it in CommonMark mode on the same input, unedited:
<p>| Task | Owner |
| --- | --- |
| Ship | Mei |</p>
Copying a rendered preview is a separate route from importing a DOCX. For desktop Word, Microsoft documents Keep Source Formatting as retaining copied formatting, while Keep Text Only discards it. A preview that already contains table cells has passed the parsing stage; changing its Markdown separator row does not control the format that reaches Word through the clipboard. Use a paste option that retains formatting, or deliver the converted DOCX. 1
The preview is therefore a diagnostic for the source parser, not a test of Word's clipboard handling. Our experiments generated HTML and inspected DOCX structure. They did not paste content into Word. A DOCX import is the route to choose when you need a document artifact instead of depending on the clipboard formats exposed by the application you copied from.
Export Word styles and inspect the changed meaning
Use Word's structural styles when the next deliverable is Markdown.
Assign a heading style before export, and keep tabular content in Word cells. Our styled fixture exported its heading through both Pandoc and MarkItDown. Enlarging and bolding the same heading text in a normal paragraph did not create a Markdown heading in either export. The Word to Markdown converter handles this direction as Signed-in Beta. 12
Pandoc's DOCX parser gets heading levels from paragraph styles. Its quotation handling also recognizes named quote styles and can infer a quotation from extra paragraph indentation. In our cosmetic fixture, the indented paragraph became a quotation through Pandoc, despite having no Quote style. MarkItDown left that paragraph as ordinary prose. 8912
MarkItDown's DOCX path passes through Mammoth's HTML conversion and then an HTML-to-Markdown converter. In our default configuration, a Word Quote paragraph lost its quotation formatting. The table had labels in its first row without an explicit header-row flag. Pandoc used those labels as Markdown headers, while MarkItDown placed them below an empty header row. The table-header failure shape also appears in the upstream special-character report. 101112
Output from our styled Word sample, unedited:
Ship **today**.
Internal only.
| | |
| --- | --- |
| Task | Owner |
| Ship | Mei |
For a local export, select the target Markdown dialect explicitly:
pandoc -f docx -t gfm --wrap=none input.docx -o output.md
| Failure condition | Visible result | What to change |
|---|---|---|
| A title is only large, bold text | It exports as emphasized prose, without a heading marker | Apply a Word heading style before export |
| Indentation is decorative | An exporter can turn it into a Markdown blockquote | Remove incidental indentation from prose that must remain ordinary text |
| Labels fall below a blank table header | The table remains readable, but its header meaning changes | Put the labels in the Markdown header position and render the corrected table |
Keep the text master when Markdown source is the lasting document. Use conversion when the handoff requires Word structure. When Word is the master, give headings and quotations explicit structure, then inspect the exported meaning of those elements.
How we tested
The tests compare document structure in local files, not Word's screen layout or clipboard behavior.
We ran the experiments on 2026-11-09 with Python 3.11.14, Pandoc 3.11, MarkItDown 0.1.8, python-docx 1.2.0, Mammoth 1.11.0, and markdownify 1.2.3. Rendering also used markdown-it-py 4.0.0 from the repository's existing environment. 1213
| Fixture | What it represents | Evidence |
|---|---|---|
literal.docx |
Markdown markers and pipe rows stored in normal Word paragraphs | literal.word-xml.txt |
styled.docx |
Heading 1, Quote, inline bold, and a native table | styled.word-xml.txt |
cosmetic.docx |
Large bold text in a normal paragraph, direct indentation, and the same native table | cosmetic.word-xml.txt |
input.md |
Active Markdown supplied directly to renderers and the DOCX writer | input.md |
The DOCX fixtures are generated by the script. They are local inputs, not public evidence attachments. The linked evidence consists of the script, extracted Word XML saved as text, Markdown exports, JSON, and HTML saved as text. 13
Run from the repository root:
PYTHONDONTWRITEBYTECODE=1 tools/lab-venv/bin/python runs/2026-11-09-markovo-markdown-for-word/lab/renderers/run.py
The script uses MarkItDown(enable_plugins=False).convert(input_path).text_content with no custom style map. Pandoc exports use -f docx -t gfm --wrap=none. The import uses -f gfm and DOCX output. The full fixture construction and subprocess commands are in the script. The reader-facing commands also passed an isolated execution check, recorded in example-receipts.json. 13
For HTML, markdown-it uses the commonmark preset with html=True and breaks=False. Pandoc uses -f gfm -t html --wrap=none. These are local implementations, not tests of GitHub.com or VS Code. Word desktop, Word for the web, clipboard behavior, the add-ins, and the Markovo API were not executed for this guide. No OCR or PDF extraction benchmark applies to these samples.
The following counts come directly from lab/renderers/results.json. We parsed each Markdown export with Pandoc's GFM reader and counted Header, Strong, BlockQuote, and Table nodes in its AST. These measure the exported structure after parsing, not document accuracy or visual fidelity. 12
| Constructed Word sample | Exporter | Header | Strong | BlockQuote | Table |
|---|---|---|---|---|---|
| Literal markers | Pandoc | 0 | 0 | 0 | 0 |
| Literal markers | MarkItDown | 1 | 0 | 1 | 0 |
| Semantic styles | Pandoc | 1 | 1 | 1 | 1 |
| Semantic styles | MarkItDown | 1 | 1 | 0 | 1 |
| Direct appearance | Pandoc | 0 | 2 | 1 | 1 |
| Direct appearance | MarkItDown | 0 | 2 | 0 | 1 |
| Direct Markdown input | h1 | strong | blockquote | table |
|---|---|---|---|---|
| markdown-it CommonMark mode | 1 | 1 | 1 | 0 |
| Pandoc GFM | 1 | 1 | 1 | 1 |
HTML counts use Python's HTMLParser start tags. The DOCX import contained a Heading1 paragraph style and a w:tbl table, recorded under import in the results and in lab/renderers/imported.word-xml.txt. The styled and cosmetic Word fixtures contain first-row labels without a w:tblHeader flag, each recorded as header_row_flags=0 in the JSON. This tests default interpretation of labels, not explicit header-row formatting. The fixtures omit images, complex tables, equations, comments, revisions, and pagination tests. Single-call timings remain in the JSON but are not a performance comparison.
Raw Pandoc exports: literal.md, styled.md, cosmetic.md. Raw MarkItDown exports: literal.md, styled.md, cosmetic.md. The quoted Pandoc literal excerpt is lines 1 through 5 of its export. The MarkItDown styled excerpt is lines 3 through 10. The Pandoc HTML excerpt is lines 6 through 12 of lab/renderers/input--pandoc-gfm.txt. The CommonMark excerpt is lines 6 through 8 of lab/renderers/input--markdown-it-commonmark.txt.
The source diagnosis traces Pandoc's pHeading, elemToBodyPart, paragraphStyleToTransform, and relativeIndent, plus MarkItDown's DocxConverter.convert. Issue #2157 reported MarkItDown 0.1.6 on Windows. Our newly constructed samples reproduce its leading-hash and empty-header failure shapes on the stated environment. They do not reproduce the reporter's original file or every subcase. 89101114
Sources
- Microsoft: control paste formatting
- Microsoft: text-file encoding
- Markdown for Word add-in listing
- Writage introduction
- Pandoc User's Guide
- CommonMark specification 0.31.2
- GFM table extension
- Pandoc 3.11 DOCX parser
- Pandoc 3.11 DOCX reader
- MarkItDown 0.1.8 DOCX converter
- MarkItDown special-character and table-header report
- Local conversion and rendering results
- Fixture generator and reproduction script
- Fixed-version source diagnosis


