Quotes, captions, names, wishes & practical how-tos

Conversion Guides

Convert HTML to Markdown Without Losing Structure

Computer desk with monitor, a typical place to convert HTML to Markdown
Photo: Vyacheslav Argenberg, CC BY 4.0, via Wikimedia Commons

To convert HTML to Markdown without losing structure, clean the HTML first, then run it through a converter such as Pandoc with an explicit Markdown flavor. Headings, paragraphs, lists, links, images, code and simple tables all have direct Markdown equivalents. Layout wrappers, inline styles and scripts do not, so removing them first gives a far better result.

Key takeaways

  • Pandoc converts HTML to GitHub Flavored Markdown with one command.
  • Trim navigation, ads, scripts and style blocks before converting.
  • Tables with merged cells and custom widgets cannot be pure Markdown and may stay as raw HTML.
  • Always diff or skim the result against the original page.

What Maps Cleanly and What Does Not

HTML is richer than Markdown, so a converter has to decide what to keep. The table below shows the usual mapping.

HTML Markdown result
<h1> to <h6> # to ######
<strong>, <em> **bold**, *italic*
<ul>, <ol> Bulleted and numbered lists
<a href> [text](url)
<pre><code> Fenced code block
<table> Pipe table, if simple
<div>, <span>, inline styles Dropped or kept as raw HTML

The Markdown syntax itself is documented on Daring Fireball, and our Markdown vs HTML comparison explains when each format makes sense.

Step 1: Clean the HTML Before You Convert

Most poor conversions come from messy input. Work through this short checklist.

  1. Copy only the main content element, such as the article body, instead of the whole page.
  2. Delete navigation menus, footers, cookie banners, share buttons and ads.
  3. Remove <script> and <style> blocks.
  4. Make sure headings use real heading tags instead of styled paragraphs.
  5. Fix broken nesting, such as list items outside a list.

If the HTML came from a word processor export, expect extra clutter. Our guide to converting Google Docs to Markdown covers that case.

Busy computer desk where you convert HTML to Markdown for documentation
Photo: apasciuto, CC BY 2.0, via Wikimedia Commons (source)

Step 2: Convert HTML to Markdown With Pandoc

Pandoc reads HTML and writes several Markdown dialects. For most uses, GitHub Flavored Markdown is the safest target because it supports tables and fenced code:

pandoc page.html -f html -t gfm --wrap=none -o page.md

Pandoc can also fetch a page directly when you give it a web address, which is handy for a quick test:

pandoc -f html -t gfm --wrap=none https://example.com/article -o article.md

If you want to keep all raw HTML out of the result, add -raw_html to the output format, as in -t gfm-raw_html. Pandoc then drops elements it cannot express instead of passing them through. The format options are explained in the Pandoc manual.

Other Ways to Convert HTML to Markdown

Libraries make it possible to build the conversion into your own tools. Turndown is a popular JavaScript library that runs in Node.js or a browser, and markdownify does a similar job in Python. Online converters are convenient for one page, but avoid pasting private content into a site you do not trust. We compare the trade-offs in Pandoc vs online Markdown converters.

A Small Example From Start to Finish

Here is a short HTML snippet with a heading, a paragraph, a list and a code sample:

<h2>Install the tool</h2>
<p>Run the command in a <strong>terminal</strong>.</p>
<ul><li>Windows</li><li>macOS</li></ul>
<pre><code class="language-bash">pandoc --version</code></pre>

After conversion with -t gfm, you should get Markdown close to this:

## Install the tool

Run the command in a **terminal**.

- Windows
- macOS

```bash
pandoc --version
```

Notice that the language class on the code element turned into the language label after the opening fence. That small detail is one reason a dedicated converter beats search-and-replace. If you want to know more about fences and inline code, see our explainer on Markdown code blocks and inline code.

Handling Many Pages at Once

If you are migrating a small site or help center, convert pages in a loop and review a sample of the results before processing the rest. Keep the original HTML files untouched in a separate folder, name the output files after the page slugs, and write down the options you used so you can repeat the run after fixing the source. A short spreadsheet listing each page, its conversion status and any manual fixes keeps larger migrations under control.

Step 3: Review the Result

Open the Markdown file and compare it with the original page. Look for the following problems:

  • Heading jumps: an H4 directly under an H2 should usually be an H3.
  • Lost images: check that every image URL is still present and add alt text.
  • Relative links: links like /about only work on the original site. Replace them with full addresses if the file will live elsewhere.
  • Tables: merged or nested tables may remain as HTML blocks. Simplify them if you want pure Markdown.
  • Extra blank lines or entities: clean up stray characters such as &nbsp;.
Home computer desk set up to convert HTML to Markdown
Photo: Ssamm T, CC BY-SA 4.0, via Wikimedia Commons (source)

Frequently Asked Questions

Can Markdown contain HTML?

Yes. Most Markdown processors pass inline HTML through, so complex pieces can stay as HTML inside a Markdown file.

Will inline styles and colors survive?

No. Markdown has no styling syntax, so colors, fonts and widths are dropped or left as raw HTML.

Which Markdown flavor should I target?

Use GitHub Flavored Markdown (gfm) unless your platform requires something else. It supports tables, task lists and fenced code blocks.

Is it safe to convert HTML from the web?

Converting text is generally safe, but do not run scripts from untrusted pages. Remove them before you convert.

Can I go back from Markdown to HTML?

Yes, and it is simpler. See our guide on how to convert Markdown to HTML.

Wrap-Up

Good Markdown comes from good HTML. Strip the clutter, convert with Pandoc and a clear flavor setting, and then review headings, links, images and tables. Do that and the structure of the original page carries across.

Written byEditorial Team

Part of the MarkdownToGoogleDocs editorial team, sharing copy-ready words and practical Markdown and Google Docs how-tos.