How do you convert HTML to Markdown, and what do you lose?

Updated: 2026-10-14 · Dawwerni team

Converting HTML to Markdown maps headings, paragraphs, emphasis, links, lists, code blocks and images to Markdown syntax, and GitHub-flavoured Markdown adds simple tables. Styling, layout, scripts and canvas charts are dropped. Use a JavaScript library such as Turndown, run pandoc -f html -t gfm, or use a free in-browser converter.

When Markdown is the right target

Markdown is plain text with a few conventions: # for headings, * or - for lists, [text](url) for links, backticks for code. It is what GitHub READMEs, most documentation sites, many wikis and note-taking apps are built on. Converting HTML to Markdown makes sense whenever the content matters more than the look and the destination is a text-first tool.

If you need to keep the visual design, Markdown is the wrong target: a PDF or an image keeps it, and an editable Word file keeps the structure with real formatting (see HTML to Word: what survives). For everything below, the free HTML to Markdown converter or one of the developer tools in this article will do the job.

• Documentation: moving pages from an old CMS or a generated HTML report into a docs repository.
• GitHub: turning an HTML page into a README.md, a wiki page or an issue description.
• Notion, Obsidian and similar tools: importing content as clean, editable notes.
• LLM context: giving an AI assistant the text of a page without thousands of tokens of tags, classes and inline styles.
• Version control: Markdown diffs are readable; HTML diffs full of attributes are not.

What converts and what is lost

Two losses deserve attention. First, charts drawn on a canvas (Chart.js, many D3 setups) contain no text, so they simply disappear; if the numbers matter, keep them as a table in the HTML or add them by hand. Second, Markdown tables cannot express colspan, rowspan or multiple paragraphs in one cell. Converters handle that differently: some flatten the table, some keep it as raw HTML inside the Markdown, which GitHub renders but other tools may not.

Method 1: Turndown in JavaScript

Turndown is the best-known JavaScript library for HTML to Markdown. It works in the browser and in Node.js, and a separate plugin, turndown-plugin-gfm, adds GitHub-flavoured tables and strikethrough. It walks the DOM and applies one rule per element, which makes it easy to customise.

npm install turndown turndown-plugin-gfm

import TurndownService from 'turndown';
import { gfm } from 'turndown-plugin-gfm';

const td = new TurndownService({
  headingStyle: 'atx',        // # Heading instead of underlined headings
  codeBlockStyle: 'fenced',   // fenced code blocks instead of indented ones
  bulletListMarker: '-'
});
td.use(gfm);                  // tables, strikethrough, task lists
td.remove(['script', 'style', 'nav', 'footer']);

const markdown = td.turndown(document.querySelector('main'));
console.log(markdown);

Convert the rendered page, not the source

Turndown converts whatever DOM you give it. Pages built by JavaScript, including most AI-generated HTML that loads Tailwind or renders content with scripts, should be converted after they have run: in the browser console of the open page, or in a headless browser. Converting the raw file with a parser that does not run scripts may give you an empty result.

Method 2: Pandoc on the command line

Pandoc does not run JavaScript, so it is ideal for static HTML exported from a CMS and less suited to pages that build themselves in the browser. When a table is too complex for a pipe table, its gfm output can fall back to an HTML table inside the Markdown file.

# HTML file to GitHub-flavoured Markdown
pandoc -f html -t gfm --wrap=none page.html -o page.md

# a whole folder (bash)
for f in *.html; do
  pandoc -f html -t gfm --wrap=none "$f" -o "$(basename "$f" .html).md"
done

Method 3: an in-browser converter, no setup

If you do not want to install anything, our HTML to Markdown tool runs entirely in your browser. You drop one or more .html files, paste code, or drop a .zip with the HTML and its assets. The page is rendered in a sandboxed iframe first, with an adjustable wait for CDN styles and scripts, and then converted to GitHub-flavoured Markdown with tables kept. Nothing is uploaded, there is no sign-up and no watermark.

It keeps the text structure only: styling and layout are dropped, and charts or canvas drawings are not converted. If you need those charts too, export the same file as images or a PDF from the AI HTML converter, which offers every format from one place.

Cleaning the result

Automatic conversion gets you 90% of the way. A few minutes of cleanup makes the Markdown pleasant to maintain.

1. Remove navigation, cookie banners, footers and share buttons before converting, or strip them with a remove rule; they become noise in Markdown.
2. Check the heading levels: a README should have one # title and ## sections. Shift levels if the page started at h2 or h3.
3. Fix images: replace absolute URLs or copy the image files next to the .md and use relative paths.
4. Look at every table; split tables with merged cells or turn them into lists.
5. Remove empty links, stray HTML comments and repeated blank lines.
6. Run a linter such as markdownlint if the file lives in a repository.

# Project name

Short description in one or two sentences.

## Installation

```bash
npm install my-package
```

## Options

| Option  | Default | Description          |
|---------|---------|----------------------|
| timeout | 3000    | Wait time in ms      |
| format  | "pdf"   | Output format        |

Destinations: GitHub, Notion and AI assistants

GitHub

GitHub renders GitHub-flavoured Markdown: pipe tables, fenced code with syntax highlighting, task lists and strikethrough. It also renders a safe subset of raw HTML, so a complex table kept as HTML still displays, but scripts, styles and most attributes are stripped.

Notion

Notion can import Markdown files and turns headings, lists, code blocks and tables into its own blocks. Importing clean Markdown usually gives a tidier page than pasting styled HTML, because there are no leftover styles to fight with.

AI assistants

When you paste a page into Claude, ChatGPT or Gemini to summarise or rewrite it, Markdown carries the same structure as HTML in far fewer tokens, so more of the content fits in the context and the model is not distracted by class names. Convert first, then paste.

Choosing a format for the rest of your files

Markdown is one output among several. If the same HTML also needs to be shared as a document, 3 free ways to convert HTML to PDF compares the options; if it is a dashboard or an infographic you want to post, save HTML as a PNG or JPG image; and if colleagues need to edit it in an office suite, the Word guide linked above covers what survives. Pick Markdown when the text is the product.