Markdown to Word with tables

How a Markdown table becomes a real Word table

Word stores a table as a w:tbl element with a grid of column widths, a list of rows, and cells that each hold one or more paragraphs. Nothing about that structure is a picture, which is why you can click into a cell, press Tab to move to the next one, sort by a column, or convert the whole thing to text. Converters that render tables as images, or that paste tab-separated text, lose all of that. MDtoDOCX writes the native structure, and the sections below explain each decision that goes into it.

Header row: shaded and repeating

The first row of a pipe table is the header. It is written with the w:tblHeader property, which tells Word to repeat that row at the top of every page when the table breaks across pages, a detail that matters for the forty-row benchmark tables people paste from CI output. Header cells are shaded light grey with bold text, the same look Word's own Table Grid style with a header gives, so the table does not look foreign next to tables made in Word.

Alignment from the separator row

Colons in the separator row set alignment per column: :--- left, :---: centre, ---: right. Each cell's paragraph receives the matching w:jc value. Right-aligning numeric columns is worth doing in the Markdown because Word cannot infer it later without selecting the column by hand. Columns with no colon default to left, as in GitHub.

Column widths are estimated, not equal

A naive converter gives every column the same width, which is why a table with an ID column and a Notes column looks wrong. MDtoDOCX measures the content of each column, taking the longest cell in characters with a cap so one long note does not dominate, and distributes the printable page width in proportion, with a minimum width so short columns remain readable. The widths are written into the table grid and the layout is set to fixed, so Word does not re-flow them on open. You can still drag any border in Word to adjust. Tables with eight or more columns automatically drop the font size to 9 points, and the Pro option places them in a landscape section so the page turns sideways for that table only.

Inline formatting inside cells

Every inline construct described on the formatting page works inside a cell: bold, italics, strikethrough, links, and inline code in Consolas with shading. Multi-line cells are written with <br> in the Markdown and become line breaks in the cell paragraph. An escaped pipe \| is a literal vertical bar. Images inside cells are scaled to the cell width, and inline formulas follow the rules on Markdown to Word with formulas. Empty cells are written as empty paragraphs so the grid stays intact.

Table style, borders and what is not possible

The table references the built-in Table Grid style and adds thin borders on every cell. Because it is a styled table, Word's Design tab offers every banded and coloured style and applying one restyles the whole table at once. When a .docx template is loaded, the template's default table style is used instead. GitHub Flavored Markdown has no syntax for merged cells, column spans or footers, so a table that needs them has to be merged in Word after export; Word's Merge Cells works normally because the cells are real. Tables are free with no row or column limit within the general 2 MB cap, and the same table engine is used for Pandoc-style pipe tables with relative widths in the dashes.

Frequently asked questions