Text

What Survives Converting a Word Document to Markdown

Markdown has no colours, fonts or page layout, so a conversion keeps structure and drops appearance. What maps cleanly, what comes out changed, and what disappears.

A page with a heading bar, text lines, a picture and a colour swatch passes a barrier; on the far side only the heading bar and text lines arrive.

Converting a Word document to Markdown keeps its structure and drops its appearance. Headings, bold, italic, links, bulleted lists and simple tables come across. Colours, fonts, alignment, spacing and page layout do not, because Markdown has no syntax for them. A few things in between come out changed: numbered lists, merged table cells and code. Others, such as comments and text boxes, disappear. The Word to Markdown converter runs in the tab, and this page lists what its code does with each case, checked against its source.

Which parts of a Word document map cleanly to Markdown?

The ones Markdown was built for. A paragraph with a heading style becomes a line starting with hash marks, at the same level, from 1 to 6. Bold, italic and strikethrough become **, * and ~~. An external hyperlink becomes [text](address). A bulleted list becomes - items, with nesting kept by indentation. A manual page break becomes a horizontal rule. Characters that Markdown would read as formatting, like a literal asterisk or underscore in your text, are escaped so they stay literal.

Headings are recognised by the paragraph style, not by how the text looks. If someone made a title by selecting a line and setting it bold at 18 points, the converter sees a bold paragraph, and you get **Introduction** instead of a heading. The same goes for Word's Title style, which is not a heading level. Before converting a document you did not write, open the Styles pane or the Navigation pane in Word. If the outline there is empty, the output will have no headings either.

Spacing is the other thing that disappears without a sign. Empty paragraphs are skipped, a tab becomes four spaces, and leading spaces at the start of a paragraph are trimmed. Markdown treats blank lines as the boundary between blocks, so the extra air some people put between sections with empty lines has nowhere to go.

What happens to tables, and to merged cells?

A simple grid converts well. Markdown's original definition has no tables at all; they come from the GitHub Flavored Markdown specification, which lists them as an extension to CommonMark. Most wikis and static-site tools read them, a strict CommonMark processor does not. That is why the converter offers HTML tables as an alternative for a processor that only knows the base syntax.

Merged cells are where a table stops converting well. Neither pipe tables nor the converter's HTML output carry a column or row span. The converter reads each cell in each row once and does not read the span setting, so a heading cell stretched across three columns becomes one cell, and the row ends up shorter than the others. Short rows are padded with empty cells on the right, which can leave the text sitting in the wrong column. A cell merged vertically leaves empty cells beneath it. The GFM specification says missing cells in a row are filled with empty ones, so other tools handle a short row the same way. Check any table that had merges before you trust it.

Two more table facts. The first row always becomes the header row, because a pipe table needs one, whether or not Word marked it as a header. And a cell with several paragraphs is joined onto one line with spaces, since a pipe table cell cannot hold a line break. A table nested inside a cell is dropped.

What is dropped, and does the converter tell you?

For some things it does. The tool shows a notice when the document contains pictures (they are left out, because Markdown refers to an image by a path and the pictures live inside the file), multiple columns (the text comes out as one), tracked changes, headers and footers, and footnotes. The header, footer and footnote notices are triggered by those parts existing in the file, so you may see one for a part that is nearly empty.

For others it does not. Comments in the margin are not read, and the text they were attached to stays in the body with no sign that a comment existed. Text inside a text box is not carried across; the notice says pictures were left out, but text in a box is lost too. Document properties like the author and title are read but not written to the output, so there is no front matter. If your static-site generator expects one, you add it by hand.

Tracked changes are resolved the way Word displays them with markup accepted: inserted text is kept, deleted text is dropped. That is convenient when you want the clean version and wrong when the point of the document was the review. Accept or reject the changes in Word first if you want to decide, not the converter.

Why do numbered lists and code come out wrong?

Numbered lists come out as bullets. Word stores numbering rules in a separate part of the file, with restarts and overrides, and the converter does not read them. A bullet is a loss you can see, where a guessed sequence could be wrong without showing. The fix is to retype 1. at the start of the items, which takes seconds. In Markdown only the first number of a list matters in most processors, so you can number them all 1. and let the renderer count.

Code is the other surprise. Text set in a monospaced font such as Courier, Consolas or Menlo becomes inline code, wrapped in backticks. A multi-line code listing in Word is several paragraphs, so you get several single-line code spans, not one fenced block. Wrap those lines in a fenced block by hand. Footnotes have a similar gap: the notes are not written, and the reference mark in the text is not either, and footnote syntax is not part of the base specification anyway.

After a conversion, compare the Markdown against the original. Pasting both into a text comparison will flag every heading that became a bold line and every list that changed. And if the problem is smart quotes and odd spaces that Word added, that belongs to a different step; why text pasted from Word goes wrong explains it.

When is Markdown the wrong target?

When the layout is the content. A form, a brochure, a letter with a letterhead, a CV with a two-column design or a document with figures and captions loses most of what makes it that document. Markdown suits text that will be styled by something else later: a README, a wiki page, a blog post, notes. If you need the document to look the same on the other end, convert it to PDF and read what changes when Word becomes a PDF.

The converter reads only .docx. An old .doc is a different binary format, and a .pages file or a renamed file will not open. Everything is read in your browser, and nothing is uploaded, which you can confirm in the Network tab of your browser's developer tools.

If you have a .docx to convert, the Word to Markdown converter lists what it left out beside the result, and you can choose hash-mark or underlined headings and pipe or HTML tables before you copy or download it.

If the file is full of look-alike quotes and odd spaces, why text pasted from Word goes wrong covers that separate problem.

Frequently asked questions

What is lost when you convert Word to Markdown?

Everything about appearance: colours, fonts, sizes, alignment, spacing and page layout. Pictures, text boxes, comments, headers, footers and footnotes are not carried across by this converter, and numbered lists come out as bullets. Headings, bold, italic, links, bulleted lists and simple tables are kept.

Why did my headings not become headings in Markdown?

The converter recognises headings by the paragraph style, such as Heading 1 to Heading 6, not by how the text looks. A line that was only made bold and larger comes out as a bold paragraph. Apply real heading styles in Word and convert again, and the levels will carry over.

What happens to merged cells in a table?

Markdown tables have no column or row spans, and this converter does not read the span setting. A merged cell becomes one cell, short rows are padded with empty cells on the right, and text can end up in the wrong column. Check any table that had merged cells against the original.

Does converting Word to Markdown keep tracked changes and comments?

Tracked changes are resolved as Word shows them: inserted text is kept and deleted text is dropped, and the tool tells you so. Comments are not read at all, so the commented text stays in the body with no trace of the comment. Accept or reject changes in Word first if the review matters.

Is the Word file uploaded when I convert it?

No. A .docx is a zip file with XML inside, and the converter opens and reads it in your browser tab. The file is not sent anywhere, and the Network tab of your developer tools will show no upload while you convert.

Last updated November 13, 2026