Word to HTML: 4 Ways to Get Clean HTML from a .docx
November 11, 2026 · 9 min read
Word to HTML: 4 Ways to Convert a .docx into Clean HTML
To convert Word to HTML cleanly, you want semantic tags like <h2>, <p> and <ul>, not Word's styling noise. Four routes get you there: Word's own Web Page, Filtered save, Pandoc, mammoth, or a Markdown round-trip through two online tools. Below is what each one keeps, what it drops and where your images end up.
Why Does Word's HTML Look So Messy?
When Word saves a document as a regular web page, it writes HTML that Word itself can reopen and edit. That's the root of the bloat. The file has to remember fonts, spacing, list numbering and print settings, so it stores them as Office-specific markup. A short heading, paragraph and bullet list typically come out like this:
<!--[if gte mso 9]><xml>
<w:WordDocument>
<w:View>Print</w:View>
</w:WordDocument>
</xml><![endif]-->
<h1><span lang=EN-US style='mso-ansi-language:EN-US'>Quarterly Report<o:p></o:p></span></h1>
<p class=MsoNormal>Sales grew <b style='mso-bidi-font-weight:normal'>12%</b>
this quarter.<o:p></o:p></p>
<p class=MsoListParagraphCxSpFirst style='text-indent:-.25in;mso-list:l0 level1 lfo1'>
<span style='font-family:Symbol'>·</span>North region<o:p></o:p></p>
The conditional comment holds Word's own settings. class=MsoNormal and the mso- properties point at Office styles, and <o:p> is an Office namespace tag that browsers don't recognise. Even the bullet isn't a real list: it's a paragraph with a Symbol-font dot and a negative indent.
Here's the same content as clean, semantic HTML:
<h1>Quarterly Report</h1>
<p>Sales grew <strong>12%</strong> this quarter.</p>
<ul>
<li>North region</li>
</ul>
That second version is what people mean by clean HTML from Word: every tag describes structure, and your site's CSS decides how it looks. Each method below gets you closer to it, by different amounts.
Method 1: Save as Web Page, Filtered in Microsoft Word
If Word is already installed, this is the zero-setup option. In the Windows desktop app:
- Open the .docx and choose File > Save As (or Save a Copy).
- In the Save as type list, pick Web Page, Filtered (*.htm;*.html).
- Choose a folder and click Save. If Word warns that Office-specific features will be removed, confirm to keep the filtered format.
The plain Web Page type keeps everything Word needs to edit the file again, including the XML blocks above. Web Page, Filtered removes those Office-specific tags, so the file gets smaller and easier to read. Images go into a companion folder named after the file (for example report_files), and the HTML links to them.
Filtered output still isn't clean, though. It keeps class=MsoNormal attributes, a long embedded style sheet and inline style= attributes. Bulleted and numbered lists usually stay as styled paragraphs instead of becoming <ul> and <ol>. A rough first pass with sed strips the classes and inline styles:
sed -E "s/ class=Mso[A-Za-z]+//g; s/ style='[^']*'//g" report.htm > report-clean.htm
Check the result by eye afterwards, because a regex can't rebuild the lists. If your goal is a .md file rather than HTML, the steps differ, and our Word to Markdown guide covers them.
Method 2: Convert DOCX to HTML with Pandoc
Pandoc reads .docx directly and writes plain, semantic HTML. It maps Word's heading styles to <h1> through <h6> and turns lists into real <ul> and <ol>. Tables, links and bold or italic text come through, and Word footnotes become a numbered endnotes section. Tables do pick up a few column-width styles, so expect a small <colgroup> block. This is the best DOCX to HTML option when you need repeatable output from the command line.
pandoc report.docx -o report.html
Without extra flags you get an HTML fragment: no <html>, <head> or <body>, which is what you want for pasting into a template. Add -s (--standalone) for a complete page with a doctype and a title.
Images need one more decision. Without a media flag, the <img> tags point at media/ paths from inside the .docx, and those files don't exist on disk. Pick one of these instead:
# Write images to a folder and link to them
pandoc report.docx -s --extract-media=assets -o report.html
# Produce one self-contained file with images embedded as data URIs
pandoc report.docx --embed-resources --standalone -o report.html
--embed-resources is the current name in Pandoc 3; the older --self-contained flag is deprecated. To convert a whole folder at once, loop over the files in your shell:
for f in *.docx; do
pandoc "$f" -s --extract-media="${f%.docx}-img" -o "${f%.docx}.html"
done
Each document gets its own HTML file and its own image folder, so names don't collide.
Two Pandoc defaults are worth knowing. Tracked changes are accepted automatically, so the HTML shows the document as if every edit was approved. Comments are dropped unless you pass --track-changes=all, which keeps insertions, deletions and comments marked up for review.
Method 3: Convert Word to HTML with mammoth
mammoth is a small converter built for one job: turning .docx into simple HTML based on the document's styles. It ignores exact fonts, text sizes, colours, underlining and table borders by default, so most of the Word noise never reaches the output. You can run it without installing anything globally:
npx mammoth report.docx report.html
The output is an HTML fragment. Images are inlined as base64 data URIs in the src attribute by default. Run npx mammoth report.docx --output-dir=out instead to write the HTML and the images as separate files into one folder.
The feature that sets mammoth apart is the style map. If your writers use custom Word styles such as Subsection Title or Aside Text, you can map each one to a real tag:
p[style-name='Subsection Title'] => h2:fresh
p[style-name='Aside Text'] => div.aside > p:fresh
Save those lines as house-styles.txt and pass them in:
npx mammoth report.docx report.html --style-map=house-styles.txt
We prefer mammoth when the HTML is headed into a CMS, because the style map turns a team's house styles into consistent markup without hand editing. There's also a Python port (pip install mammoth) if your pipeline runs on Python. One caution from the project itself: mammoth doesn't sanitise its output, so treat documents from untrusted sources carefully.
Method 4: Go Through Markdown with docx-to-md and md-to-html
If you'd rather not install anything, you can route the document through Markdown in the browser. Markdown can only express structure (headings, lists, emphasis, links, tables), so almost none of the styling noise survives the trip.
- Upload the .docx to our DOCX to Markdown tool. It runs on the server, accepts .docx only, and spends one operation from the free pool of 3 a day.
- Paste the Markdown into the editor. The live preview on the right shows whether headings, lists and tables came through, so you can fix them before converting.
- Copy the Markdown into the Markdown to HTML converter. It runs entirely in your browser, has no usage limit, and returns a full HTML document.
The editor's own Export as HTML also works. It runs on the server, though, so it draws on the same daily pool, and free users can export documents up to 5,000 characters.
The limitation is real: this round-trip drops colours, fonts, comments and text box layout. Tables with merged cells flatten, because Markdown tables can't merge. For a report or an article, that's usually fine. For a designed brochure, use Method 1 and keep the look. If the document is only unformatted paragraphs, converting plain text to HTML is simpler still.
How Do I Convert DOCX to HTML with Images?
Every method handles embedded pictures differently, and that choice matters as much as the HTML itself.
| Method | Where images go | How to change it |
|---|---|---|
| Web Page, Filtered | A _files folder next to the HTML | Fixed; upload the folder with the page |
| Pandoc | Linked paths that don't exist yet | --extract-media=DIR, or --embed-resources --standalone |
| mammoth | Base64 data URIs inline | --output-dir=DIR for separate files |
| docx-to-md route | Base64 data URIs inside the Markdown | Swap them for hosted image URLs before converting |
Base64 keeps everything in one file, which is handy for email or a quick preview. It also makes each image about a third larger than the original file, and some CMS editors strip data URIs on paste. For a real web page, write images to files and upload them alongside the HTML.
Which Word to HTML Method Should You Use?
Pick based on where the HTML is going and how many files you have.
| Situation | Method and where it runs | What you get |
|---|---|---|
| One-off, Word installed, look matters | Web Page, Filtered, in the Word desktop app | Keeps fonts, colours and most formatting. Drops Office-only tags and XML. |
| Many files, scripts or CI | Pandoc, on your machine | Keeps headings, lists, tables and footnotes. Drops fonts, colours and layout. |
| Pasting into a CMS | mammoth, on your machine (Node or Python) | Keeps structure plus mapped house styles. Drops fonts, sizes, colours and borders. |
| No installs, single document | docx-to-md, then md-to-html, in your browser and on our server | Keeps headings, lists, tables and links. Drops styling, comments and merged cells. |
If you're unsure whether you need HTML at all, our comparison of Markdown vs HTML explains when each format fits. If your source is a PDF rather than a .docx, the tools change, and our PDF to HTML guide covers them.
Word to HTML FAQ
The right Word to HTML route depends on where the markup is going. Use Word's Filtered save for a quick look-alike page, Pandoc for batches and mammoth for CMS-ready markup. For one document with no installs, convert it with the DOCX to Markdown tool, tidy it, then paste it into the Markdown to HTML converter.