GuideBy MarkovoPublished October 29, 2026

Convert MD to Word with tables and styles

Use Pandoc's GFM reader to convert an MD file to Word, and apply a reference document after the tables and equations survive. The source falls into four cases: ordinary Markdown documents, mathematical notes, embedded HTML, and documents that only need a change of Word styles.

Choose the route from the source syntax

Match the conversion route to the syntax that carries the content.

These cases can coexist in the same file. A pipe table and an HTML table can look alike in a Markdown preview while producing different Word output. Our mixed table sample kept the pipe table during direct conversion and lost the embedded HTML table. Changing the heading style did not recover the missing content. ⁵

Convert native Markdown structures with Pandoc

Pandoc's GFM reader preserves the native structures in our Markdown sample.

With Pandoc installed, the direct route is:

pandoc -f gfm input.md -o output.docx
        

The reader decides whether the source contains a heading, table or equation before the Word writer receives it. A writer can create a valid Word file from plain paragraphs while leaving the intended table as text. ²

Output from our ordinary Markdown sample, unedited:

| Topic         | Owner  |
        |---------------|--------|
        | Accessibility | Team   |
        | Documentation | Editor |
        

In the generated Word file, the table remained an editable table. The headings referenced heading styles, and the ordered list retained its numbering start. ⁵

The same input passed through the plain CommonMark reader produced pipe characters in a paragraph instead of a Word table. Changing the reference document would style that paragraph, but it would leave the table absent. For a document with pipe tables, choose the reader that recognizes the table syntax before adjusting borders or fonts. ⁵

Output from the same sample through CommonMark, unedited:

\| Topic \| Owner \| \| --- \| --- \| \| Accessibility \| Team \| \| Documentation \| Editor \|
        
            status = "ready"
            print(status)
        

GFM also recognized the mathematical note's dollar-delimited expressions and produced native Word equation objects. Plain CommonMark left those expressions as ordinary text. Dollar math was already enabled in the tested GFM configuration. ⁵

Re-parse embedded HTML when direct conversion drops it

Re-parsing embedded HTML restores the table and line break that direct conversion drops in our sample.

The failure was more specific than a broken table layout. The native pipe table survived, but a contact cell joined the editor and reviewer names. The separate HTML table disappeared entirely. The conversion process still completed and wrote a document. ⁵

Output from our mixed table sample, unedited:

| Item   | Contact        |
        |--------|----------------|
        | Report | EditorReviewer |
        

The missing break and missing table follow different branches of the same mechanism. In the tested writer's source, foreign raw blocks are filtered before native blocks are converted. Raw inline HTML also has no general Word rendering path, while a native line break does. ²

The upstream HTML-table issue describes this failure in an older Pandoc release. A separate discussion records HTML breaks disappearing inside cells. Our own samples reproduce both shapes with the installed version; they do not establish that every attachment or every case from those reports behaves identically. ^{3 4}

For a document that needs these embedded elements, the tested bridge is:

pandoc -f gfm -t html --mathml input.md -o intermediate.html
        pandoc -f html intermediate.html -o output.docx
        

The first command preserves the embedded table in HTML. The second reads that HTML into document objects before writing Word. The math option carries recognized equations through the intermediate document as MathML. Our mathematical sample retained native equations through this route as well. ⁵

Output from our HTML table after the bridge, unedited:

| Format   | Owner    |
        |----------|----------|
        | Markdown | Author   |
        | Word     | Reviewer |
        

The contact cell also regained a line break. That success applies to the simple table and break in the sample. It does not demonstrate support for arbitrary page CSS, scripts, complex merged headers or a browser application's private syntax. ⁵

The bridge adds a representation change, and the direct path already handles the native structures tested here.

Apply Word styles after the content survives

A reference document changes Word styles after parsing has decided which content exists.

Start with Pandoc's default reference document, edit the relevant styles in Word, and supply it during conversion:

pandoc -o reference.docx --print-default-data-file reference.docx
        pandoc -f gfm input.md --reference-doc=reference.docx -o output.docx
        

Pandoc uses the reference's styles and document settings while ignoring its body content. A paragraph in the reference document is therefore not a placeholder that automatically becomes part of the output. Put recurring cover text in the Markdown input if it belongs in every generated report. ¹

Our reference test changed the heading-size definition and inserted a distinctive marker into the reference's body. The generated file received the changed style definition without copying the marker. The embedded HTML table remained absent. ⁵

Output from our styled handoff sample, unedited:

# Review handoff
        
        ## Editorial decision
        
        The report is ready for comments.
        

The excerpt preserves the headings and the handoff text, while the embedded table is still absent. ⁵

Keep the Markdown source and its reference document together for repeated generation. During a Word review, treat the generated copy as the active review document. Move accepted content edits back into the Markdown before generating another copy, or a new export can replace the text reviewers changed.

If the edited Word document becomes the starting source for the next Markdown revision, Markovo's Word to Markdown converter covers that reverse step in Signed-in Beta. Check that the resulting Markdown contains the intended table header and separator before exporting it to Word again.

To convert an MD file to Word for review, use the direct GFM route for native content, the HTML bridge for the embedded elements demonstrated here, and a reference document for appearance. If a table is absent, change the reading route. If the table exists and needs a new style, change the reference.

How we tested

The tests isolate parsing, Word object creation and style import; they do not measure visual layout fidelity.

The corpus contains owned synthetic Markdown fixtures. The ordinary document tests headings, an ordered list, a pipe table, a link and fenced code. The mathematical note tests inline and display math. The mixed HTML document tests an embedded table and a break inside a pipe-table cell. The style document tests heading styles alongside an embedded table.

Execution date: 2026-10-29. Pandoc: 3.11. Python: 3.11.14. The system and exact commands are recorded in the raw results. No packages were installed for this guide.

Run from the repository root:

PYTHONDONTWRITEBYTECODE=1 tools/lab-venv/bin/python runs/2026-10-29-markovo-convert-md-to-word/lab/renderers/run.py
        

The script executes these configurations for every input, using input.md and output.docx below as replaceable filenames:

The reference starts with pandoc -o reference.docx --print-default-data-file reference.docx. The script changes Heading1's w:sz from 40 to 56 half-points and adds a body marker. The output receives the style change without copying that marker. This checks the stored style definition, not its appearance in Word.

Before each conversion, the runner also executes pandoc -f READER -t json INPUT to preserve the reader's document model. It reads the generated DOCX as a ZIP archive, counts native objects, and saves the exact word/document.xml bytes in a .xml.txt file. It then runs pandoc -f docx -t gfm --wrap=none OUTPUT.docx to create the readable .md witnesses quoted above. Those excerpts are unedited reverse conversions, not screenshots or layout evidence. Full substituted argument lists are preserved for every row. ^{5 6}

tools/lab_score.py measures extraction into Markdown, including sentence recall and table-row string matches. Those definitions do not measure native Word objects, so this rendering experiment does not produce an extraction score. Its counters are defined in results.json: headings count paragraph references to heading styles. Tables, rows and cells count their native Word elements. Equations count m:oMath. Breaks count w:br. The heading-size column reads the stored Heading1 style in half-points. None is a weighted quality score or a claim that an equation is mathematically correct.

All configurations use the same Pandoc writer. This is a comparison of parsing and styling routes within one engine, not a benchmark of competing services. The GFM label denotes the local Pandoc implementation. GitHub.com and VS Code were not tested. A macOS textutil attempt reported a helper-application error and produced no DOCX even though its process returned zero. It is excluded from the successful rows. The error text is retained.

Raw outputs follow lab/renderers/<configuration>/<sample>.md, with corresponding .ast.json and .xml.txt files. The HTML bridge also retains .html.txt output. The reproduction notes describe the reference control, and the source diagnosis names the writer branches. ⁷ Local DOCX artifacts can be regenerated by the script. They are excluded from the publishable evidence list.

No Word, Pages or LibreOffice layout acceptance was performed. The fixtures do not cover image embedding, elaborate merged tables, arbitrary CSS, diagram rendering or complete round-trip fidelity. No timing comparison is drawn from the individual subprocess durations. The pre-existing PDF and input-to-Markdown results are unrelated to this direction and are not used. Markovo was not tested as a Word exporter. This guide addresses conversion structure. The reverse-workflow product link is not conversion evidence.

Sources

1. Pandoc reference-document documentation
2. Pandoc 3.11 DOCX writer source
3. Upstream HTML-table report
4. Upstream HTML-break discussion
5. Raw experiment results
6. Reproduction script
7. Fixed-version source diagnosis