On-device AI — professional-grade, fully private.

Documents

How to Convert Word to Markdown (DOCX to .md With Tables, Links and Images)

Convert Word to Markdown online: headings, lists, tables, links and images come through cleanly. See what cannot convert (layout, comments, colours) and why.

Updated November 8, 20268 min read

To convert Word to Markdown, open a DOCX to Markdown converter, add your .docx file and copy or download the .md result. The structure of the document is what carries across: headings become # lines, bullet and numbered lists become - and 1. items, bold and italic become ** and *, links stay clickable, tables become pipe tables and pictures become image references. What does not carry across is the look of the page. Markdown is plain text with a little punctuation, so fonts, colours, margins, columns and Word comments have nowhere to go. Knowing which side of that line each part of your document sits on is the difference between a clean file and an afternoon of fixing it by hand.

How to convert Word to Markdown, step by step

1

Add the .docx file

Open the Word to Markdown converter and drop the document on it, or press Choose file. Only .docx is accepted. An older .doc file is refused with a message, because it is a different format: open it in Word or Google Docs and save it as .docx first. Conversion starts by itself.

2

Pick the Markdown flavour

Leave it on GitHub for GitHub, GitLab, most wikis and most static site generators. Choose CommonMark only for a strict parser, or Pandoc if the file goes into a Pandoc pipeline. The table further down shows what changes.

3

Decide what happens to images

Under Embedded images choose Extract (pictures go into an images folder and the download becomes a ZIP), Inline (pictures are written into the .md file itself) or Leave out.

4

Set the optional extras

Demote headings pushes every heading down one to three levels, so a document whose title is Heading 1 can sit under an existing page title. Line width wraps paragraphs at 80 or 100 columns, or not at all. Add YAML front matter writes the title, author, subject, keywords and dates from the document properties at the top of the file.

5

Check the preview, then copy or download

Switch between Source (the exact text you will take away) and Rendered (how a Markdown renderer will show it). Then press Copy, Download .md, or download the ZIP if you extracted images. Settings re-render the preview straight away, so try a few before you commit.

What converts cleanly

Anything that describes the structure of the text has a Markdown equivalent or a safe HTML fallback, and the converter writes it out rather than flattening it into plain paragraphs.

In WordIn the Markdown fileWorth knowing
Heading 1 to Heading 6 styles# to ###### headingsOnly text with a real Heading style counts; big bold text stays a paragraph
Bulleted and numbered lists- items and 1. itemsNesting is kept to any depth
Bold, italicDouble and single asterisks around the textText in a code character style becomes inline code
Strikethrough~~text~~Written as <s> HTML in CommonMark
HyperlinksMarkdown linksThe link text and the address both survive
TablesPipe tables with column alignmentMerged cells or lists in a cell make that table HTML
Footnotes and endnotes[^1] references with definitions at the endNumbered HTML list in CommonMark
PicturesImage references such as images/image-1.pngThe alt text you set in Word becomes the image description
Quote and code paragraph styles> blockquotes and code blocksMatched by Word's style names, such as Quote and Code
Underline, highlight, superscript, subscript<u>, <mark>, <sup>, <sub> HTMLPandoc writes ^sup^ and ~sub~ instead

Tables deserve a note of their own. The column alignment (left, centred, right) is read from the document and written as ---, :---: and ---:. If Word marked a row as a repeating header row, that row becomes the header; if no row is marked, the first row is used, because a pipe table must have one. A pipe character inside a cell is escaped so it cannot split the column, and two paragraphs in one cell are joined with a line break. When a table uses merged cells, Markdown simply has no syntax for it, so that one table is written as HTML, which every common Markdown renderer displays correctly. The result card tells you how many tables took that route.

What cannot be converted, and why

Markdown was designed to describe what text is, not how it looks. The things below are not lost because of a weak converter; there is no Markdown to write them in.

  • Page layout. Margins, page size, page breaks, section breaks, multiple text columns and the position of floating pictures or text boxes. A Markdown file has no pages; it is one flow of text that the destination lays out.
  • Comments. Review comments in the margin are not written into the .md file. If the comments matter, resolve or copy them out before converting.
  • Colours, fonts and sizes. Font colour, font family, point size and line spacing are dropped. Highlighting is kept only as a <mark> tag, which most renderers show in their own default colour, not yours.
  • Headers and footers. Page headers, footers and page numbers belong to the page layout and are not part of the converted text.
  • Alignment of normal paragraphs. Centred or right-aligned body text becomes ordinary left-aligned paragraphs. Only table columns keep their alignment.
  • Manual formatting pretending to be structure. A line made bold and 16 pt looks like a heading in Word but is just a paragraph to any converter. Lines started with a typed dash or number instead of a real list become paragraphs that begin with that character.

Which Markdown flavour to choose

Markdown is a family of dialects. They agree on headings, lists, emphasis and links and disagree on the rest, and the wrong choice shows up as stray tildes and pipes on the page.

FlavourTablesStrikethrough and footnotesUse it for
GitHub (default)Pipe tables~~text~~ and [^1]GitHub, GitLab, wikis, most static site generators and note apps
CommonMarkHTML tablesHTML <s> and a numbered notes listStrict parsers that reject extensions
PandocPipe tables~~text~~ and [^1], plus ^sup^ and ~sub~Files that Pandoc will convert again

If you are not sure, keep GitHub. CommonMark output is correct everywhere but more verbose, because every table and footnote falls back to HTML.

Images: extract, inline or leave out

Extract is the right choice for a repository, a docs site or a static site generator. Each picture is saved as images/image-1.png, images/image-2.png and so on, the Markdown points at those relative paths, and the download is a ZIP holding the .md file and the folder. Unzip it as one unit so the paths keep working. Inline turns each picture into a data URI inside the text. The file needs nothing beside it, but a single photo can add megabytes of unreadable characters, so keep it for short snippets pasted somewhere that cannot host files. Leave out writes no image references at all, which suits a migration where the pictures already live elsewhere.

On the free plan, extracted images are written at up to 4096 pixels on the longest side, which is larger than any normal documentation page displays them. Pro keeps them at their original resolution.

Tables, footnotes, links, images and YAML front matter, in GitHub, CommonMark or Pandoc flavour. Free: one .docx at a time up to 50 MB, every conversion setting included, images up to 4096 px. Pro: batches of up to 50 documents in one ZIP and full-resolution images. It all runs on your device, not our servers.

Convert Word to Markdown

Getting a clean result: prepare the document first

  1. 1Apply real Heading styles to every heading, and make sure there is only one Heading 1 if the file will become a single page.
  2. 2Use Word's bullet and numbering buttons for lists, not typed dashes or numbers.
  3. 3Add alt text to pictures (right-click a picture and choose the Alt Text option). It becomes the image description in the Markdown, which screen readers and search engines read.
  4. 4Unmerge table cells where you can. A plain grid becomes a readable pipe table; a merged one becomes HTML.
  5. 5Fill in File > Info > Properties (title, author, subject, tags) if you want useful YAML front matter.
  6. 6If the file is over 50 MB, the size is almost always the pictures. Compress the Word document first, and see compressing a Word document for what that changes.

When Markdown is the wrong target

Markdown is ideal when the text will be edited, versioned or published by a site that applies its own styling. If the point is to keep the document looking exactly as it does in Word, it is the wrong format. For a printable copy that keeps every page as designed, use Word to PDF; what survives a Word to PDF conversion covers fonts and layout there. If the destination wants HTML rather than Markdown, Word to HTML writes it directly. If you only need the words, Word to Text gives you plain text with no markup to clean up.

If your table started life in a spreadsheet rather than a Word document, skip Word entirely: converting CSV to Markdown explains how to turn the data straight into a pipe table with the CSV to Markdown tool.

Frequently asked questions

How do I convert a Word document to Markdown?

Add the .docx to the Word to Markdown converter, choose a flavour (GitHub is the default), choose what happens to images, check the Rendered preview and press Copy or Download .md. Free converts one document at a time up to 50 MB.

Can I convert DOCX to Markdown with tables?

Yes. Word tables become pipe tables with their column alignment read from the document. A table with merged cells, or with a list inside a cell, has no pipe-table equivalent, so it is written as an HTML table, which Markdown renderers display normally.

Why are my headings plain text after converting?

The document used bold or larger text instead of Word's Heading styles. A converter can only recognise a heading that is marked as one. Apply Heading 1, 2 or 3 in Word and convert again.

Are Word comments and font colours kept in the Markdown?

No. Markdown has no syntax for review comments, font colours, fonts, sizes or page layout, so they are not written into the .md file. Highlighting is kept as a <mark> tag and underline as <u>.

Can I convert a .doc file to Markdown?

Not directly. Only .docx is accepted. Open the .doc file in Word or Google Docs, save or download it as .docx, then convert that.

Can I convert several Word files to Markdown at once?

Batch conversion is a Pro feature: up to 50 documents in one go, collected into a single ZIP with every .md file and its images. On the free plan you convert one document at a time, with every setting available.

Keep reading

More in Documents →