DOCX to Markdown: keep headings, lists and tables

Converting DOCX to Markdown means turning the text of a Word document into plain Markdown that you can paste into notes, a README or a prompt. The free DOCX to Markdown tool reads the document body and writes headings, paragraphs, bulleted and numbered lists, tables and code as Markdown. It does not carry over images, comments, tracked-change history or page layout. This guide shows what a real Word file becomes, which parts to check before you paste, and where the converter stops.

What a .docx file holds

A .docx file is not one stream of text. It is a ZIP package of XML parts, and Word stores each component as its own entry. The words of the main document sit in a part called document.xml. Comments, headers, footers and footnotes are kept in other entries of the same archive. Microsoft's WordprocessingML documentation describes that structure, and you can see it yourself by opening a copy of a document with an archive tool.

That layout explains most of what a converter can and cannot do. A converter that reads the body has to find the paragraphs, styles and tables inside document.xml and write each one as the matching Markdown. Pictures are stored as separate image parts, and text held in other parts is outside that path. The Lass0 tool is built to read the body and says so on its own page. It does not claim to read everything in the package.

The size of the package matters too. Word compresses its parts, and a document that is mostly pictures can be large while holding little text. Choose a tool by what it reads, not by how much file it accepts.

A worked example with a real Word file

The converter's test suite includes a real Word file called review.docx. It has a title, two sections, a bulleted list, a numbered list, a three-row table and one line of code. The file is small enough to read in one pass, which makes a mismatch easy to spot. It is 37,130 bytes, about 0.35 per cent of the 10 MB upload limit.

The output below comes from the same parsing and rendering code the tool calls, run on that file. It is the whole Markdown result, not an excerpt.

Table: what to check after conversion

The tool writes this Markdown for the file:

# Quarterly review

Revenue grew in every region this quarter. The team shipped the new billing flow on time.

## Highlights

- Churn fell to 2.1%
- Two new enterprise customers
- Support replies under four hours

## Next steps

1. Hire a second designer
2. Move reporting to the warehouse

| Region | Revenue | Growth |
| --- | --- | --- |
| Europe | £1.2m | 14% |
| Americas | $2.4m | 9% |

```
SELECT region, sum(total) FROM orders GROUP BY region;
```

Questions go to the finance channel.

Read the result against the Word file, not against your memory of it. Each heading level, list item and table cell should match what you see in Word. Look closely at the currency symbols and percentages. £1.2m and 14% come through exactly as typed, which matters: a converter that rewrote numbers would change the figures you paste without warning.

The Word file is 37,130 bytes, and its Markdown is 95 words and 494 bytes long. Most of the file's bytes are package data, styles and layout rather than text. That is why a file size limit says little about how much text a document holds.

Headings and lists come from structure

Headings are the first thing to check, because the outline is what readers and other tools use to find their way around. The converter maps the heading styles of the file: the title becomes a first-level Markdown heading, and the two section names become second-level headings. Use Word's built-in heading styles for section titles. A bold line looks like a heading, but Word does not record it as one, and a converter reads the file's structure, not its appearance.

Lists work the same way. The three bullets become three lines that start with a hyphen, and the two numbered steps become lines starting with 1. and 2. The items stay in their original order. Check the counts anyway. A missing item is far easier to see before you paste than after the Markdown has moved into a document.

Tables are the riskiest part

Tables fail in more specific ways. The converter writes a pipe table, and the GitHub Flavored Markdown specification defines that syntax as an extension to CommonMark. In the specification, the header row must have the same number of cells as the delimiter row, or the table is not recognised. A table also cannot hold block content, so a cell cannot contain a second paragraph or a code block. Literal pipe characters need a backslash in front of them, and a blank line ends the table.

Markdown has no syntax for merged cells. A Word table that depends on them cannot keep its shape in the output, so compare any such table with the original before you use it. Nested tables and cells with several lines of text have the same problem. The fixture's table is simpler. Its header row reads Region, Revenue and Growth, followed by rows for Europe and Americas. Every row has three cells, which is the shape the specification asks for.

Test one table before you convert a whole report. Choose the table with the most cells, convert the file and compare every cell with the original. If that table is clean, the simpler tables are likely to be clean as well. If it is not, the problem is usually in the structure of the Word file, and the fix belongs there.

What does not come through

The tool's own limitations list is short, and it is worth reading before you convert a document you care about. The tool reads body text, headings, lists and tables. These are not preserved:

• embedded images
• comments
• footnotes
• tracked-change history
• page layout

Links become their visible text, so the address behind a link is lost unless it appears in the text. Legacy .doc files and scanned pages are not supported.

Two further behaviours come from the parser itself. It skips deleted revisions, so text you deleted with tracking on does not reappear. It also skips field instructions and keeps only the result a field shows. A field that displays a date gives you the date, not the code that produced it.

When a file has no readable body text, the tool stops with an explicit message rather than returning an empty document: “No body text was found. Images and scanned pages are not read by this tool.” An empty result would look like success, which is why the message is worth keeping.

Check the output before you paste

A short check takes less time than repairing a pasted document later. Keep the original open beside the output and work through these steps:

• Compare each heading with the Word outline, including its level.
• Count the items in each list.
• Spot-check every table row against the cells in Word, paying attention to currency symbols and percentages.
• Read each code block against the source, because nothing in it should change.
• Look for any sentence that refers to a picture, chart or attachment, and decide where that content should live.

Then decide what the missing pieces need. A chart or a screenshot of a table cannot come across as text. Put it back by hand, or keep the original file beside the Markdown so the source stays one click away.

Limits and where the document goes

The tool accepts a .docx file up to 10 MB. It stops if the package expands beyond 32 MB when unpacked. If the Markdown would exceed 200,000 characters, the tool asks you to split the document. For a long report, split it by section, convert each part and join the results. The tool page says the conversion happens without uploading the document. Read the tool page for the current limits before you rely on them.

When the source is a PDF

Word files are structured, so the converter can read their headings and tables directly. PDFs are harder, because a PDF records where text sits on the page, and the reading order, headings and table cells must be inferred. If your source is a PDF, start with how to convert PDF to Markdown, check table rows with PDF table to Markdown, and read copy text from PDF if selection or broken lines are the problem. For text that goes into a language model, PDF to Markdown for LLMs covers how to prepare the input.

Questions, answered

Does the converter keep images from a Word document?

No. Embedded images are not preserved. A file with no readable body text, such as one made only of pictures or scanned pages, gets an explicit message rather than an empty Markdown file.

Are comments and tracked changes in the Markdown?

No. Comments, tracked-change history and footnotes are not preserved, and deleted revisions are skipped. Accept or reject the changes in Word before you convert, so the text you convert is the text you mean to keep.

Can it convert an old .doc file?

Not with this tool. Legacy .doc files are not supported. Open the file in Word or LibreOffice, save a new .docx copy and convert that copy.

What are the size limits?

A file up to 10 MB, a package that expands to no more than 32 MB, and up to 200,000 characters of Markdown output.