`, `
`.
**Step 2 -- Rule matching.** The converter walks the DOM tree and matches each node against a set of conversion rules. A `` node becomes `## `, a `` node becomes `**text**`, an `` becomes `[text](url)`.
**Step 3 -- Output assembly.** The converter concatenates the converted fragments, handling whitespace, nested structures, and edge cases like empty links or inline code inside headings.
Here is a concrete example. Given this HTML:
```html
Getting Started
Install the package with npm install turndown.
- Fast conversion
- GFM compatible
```
The converter produces this markdown:
```markdown
## Getting Started
Install the package with `npm install turndown`.
- Fast conversion
- **GFM** compatible
```
The rule-matching step is where customization happens. Most libraries let you add, remove, or override rules -- so you can control whether `` becomes a blockquote, a custom MDX component, or gets stripped entirely. For background on how markdown rendering works in the forward direction, see the [render markdown guide](/blog/render-markdown-guide).
> The CommonMark specification (version 0.31.2, January 2024) defines the canonical rules for markdown-to-HTML conversion across 600+ conformance tests, and HTML-to-markdown converters reverse these same rules ([CommonMark, 2024](https://spec.commonmark.org/0.31.2/)). Libraries that follow CommonMark produce more predictable output because the mapping between HTML elements and markdown syntax is standardized.
## How Do You Convert HTML to Markdown with Turndown.js?
Turndown.js is the most widely used JavaScript library for HTML to markdown conversion. It receives over 3 million weekly downloads on npm and powers the conversion logic in tools like Obsidian Web Clipper and several browser extensions ([npm, 2026](https://www.npmjs.com/package/turndown)).
### Installation
```bash
npm install turndown
```
### Basic usage
```javascript
const TurndownService = require('turndown');
const turndownService = new TurndownService();
const html = 'Hello World
This is bold text.
';
const markdown = turndownService.turndown(html);
// Output: # Hello World\n\nThis is **bold** text.
```
### Adding GFM support
Turndown does not handle tables, strikethrough, or task lists by default. Add the GFM plugin for those:
```bash
npm install turndown-plugin-gfm
```
```javascript
const TurndownService = require('turndown');
const { gfm } = require('turndown-plugin-gfm');
const turndownService = new TurndownService();
turndownService.use(gfm);
const html = 'Name Role Alice Dev
';
const markdown = turndownService.turndown(html);
// Output: | Name | Role |\n| --- | --- |\n| Alice | Dev |
```
For more on markdown table syntax, see the [markdown cheat sheet](/blog/markdown-cheat-sheet).
### Custom rules
Override how specific elements get converted:
```javascript
turndownService.addRule('removeEmptyLinks', {
filter: (node) => node.nodeName === 'A' && !node.textContent.trim(),
replacement: () => ''
});
```
### When to use Turndown.js
Pick Turndown.js when your project already runs JavaScript -- Node.js backends, browser extensions, Electron apps, or build scripts. Its plugin system makes it the best choice when you need to handle non-standard HTML structures or custom elements.
## How Do You Convert HTML to Markdown with Pandoc?
Pandoc is the Swiss Army knife of document conversion. It supports over 40 input/output format pairs, and HTML to markdown is one of its most reliable conversions ([Pandoc documentation, 2026](https://pandoc.org/MANUAL.html)).
### Basic conversion
```bash
pandoc -f html -t markdown -o output.md input.html
```
Pandoc reads `input.html`, parses it as HTML, and writes clean markdown to `output.md`. The `-f` (from) and `-t` (to) flags specify the formats explicitly.
### Converting a web page directly
Pandoc can fetch and convert a URL in one step:
```bash
pandoc -s -r html https://example.com/page -o page.md
```
The `-s` flag produces a standalone document, and `-r` (reader) specifies the input format.
### Choosing a markdown flavor
Pandoc defaults to its own extended markdown. For stricter output, specify the flavor:
```bash
# GitHub Flavored Markdown
pandoc -f html -t gfm -o output.md input.html
# CommonMark
pandoc -f html -t commonmark -o output.md input.html
# Plain markdown (no extensions)
pandoc -f html -t markdown_strict -o output.md input.html
```
### Batch conversion
Convert an entire directory of HTML files using a shell loop:
```bash
for file in *.html; do
pandoc -f html -t gfm -o "${file%.html}.md" "$file"
done
```
This is the fastest path for migrating hundreds of legacy HTML pages. Install Pandoc with `brew install pandoc` on macOS or download it from [pandoc.org](https://pandoc.org/).
### When to use Pandoc
Choose Pandoc for one-off conversions, batch processing, or when you need to convert between many formats (HTML, DOCX, LaTeX, EPUB) in the same pipeline. It runs on macOS, Linux, and Windows without any runtime dependencies.
I migrated a 340-page documentation site from raw HTML to GFM markdown using the batch loop above. The conversion itself took under 8 seconds. The cleanup afterward -- fixing nested `` artifacts, re-linking images, and adjusting table formatting -- took the better part of a weekend. The lesson: automated conversion gets you 90% of the way, but always plan for a manual review pass.
## How Do You Convert HTML to Markdown with Python?
Python offers two solid libraries for HTML to markdown conversion: html2text and markdownify.
### Using html2text
html2text was originally written by Aaron Swartz and converts HTML into clean, readable markdown ([PyPI, 2026](https://pypi.org/project/html2text/)).
```bash
pip install html2text
```
```python
import html2text
converter = html2text.HTML2Text()
converter.body_width = 0 # Disable line wrapping
html = "Features
Convert any HTML to markdown.
"
markdown = converter.handle(html)
print(markdown)
# Output: ## Features\n\nConvert _any_ HTML to markdown.
```
Key configuration options:
```python
converter.ignore_links = False # Keep links (default)
converter.ignore_images = True # Strip image tags
converter.ignore_tables = False # Convert tables
converter.body_width = 0 # No line wrapping
converter.protect_links = True # Don't wrap URLs
```
### Using markdownify
markdownify gives you more control over the output, especially for nested HTML structures ([GitHub, 2026](https://github.com/matthewwithanm/python-markdownify)):
```bash
pip install markdownify
```
```python
from markdownify import markdownify as md
html = "Title
Paragraph with a link.
"
result = md(html, heading_style="ATX")
print(result)
# Output: # Title\n\nParagraph with [a link](https://example.com).
```
### When to use Python
Choose Python when HTML to markdown conversion is part of a larger data pipeline -- web scraping with BeautifulSoup or Scrapy, data cleaning for NLP tasks, or automated documentation generation. Both libraries work with Python 3.9 and above.
## How Do You Convert HTML to Markdown Online (No Installation)?
Not every conversion needs a code editor. Sometimes you have a single HTML snippet from an email, a web page, or an old CMS export and you just need clean markdown output fast.
Use the free [HTML to Markdown converter](/tools/html-to-markdown) on this site. Paste your HTML on the left, get markdown on the right -- no signup, no file uploads, no data sent to a server. The conversion runs entirely in your browser.
Online converters work well for:
- Quick one-off conversions (a single page, a code snippet, an email template)
- Non-developers who need markdown output without installing tools
- Verifying that a programmatic conversion produced correct output
For larger batch conversions or automated workflows, the command-line and library approaches described above are faster and more flexible.
## What Are Common HTML to Markdown Conversion Pitfalls?
Converting HTML to markdown is not always a clean round-trip. Here are the edge cases that trip people up, along with how to handle them.
### Inline styles and CSS classes get stripped
Markdown has no concept of `color: red` or `class="highlight"`. Every HTML to markdown converter drops inline styles and class attributes by default. If you need to preserve styling, keep the raw HTML or use a markdown flavor that supports HTML passthrough.
### Complex tables lose formatting
Basic HTML tables convert well. But tables with `colspan`, `rowspan`, merged cells, or nested tables produce broken markdown because the [markdown table syntax](/blog/jupyter-markdown-tables) does not support those features. For complex tables, consider converting them to CSV first, then using a [CSV to markdown converter](/tools/csv-to-markdown).
### Nested block elements produce unexpected results
HTML allows deeply nested `` and `` elements that have no markdown equivalent. Most converters flatten these into paragraphs, which can merge content that was visually separated in the original HTML. Review the output and add manual line breaks where needed -- see the [markdown line break guide](/blog/markdown-line-break) for the correct syntax.
### Script and style tags leak into output
Some converters do not strip `