---
title: "HTML to Markdown"
slug: html-to-markdown
date: 2026-10-18T14:19:49+00:00
modified: 2026-10-18T14:21:44+00:00
permalink: https://brightdata.com/glossary/html-to-markdown
type: page
---

# HTML to Markdown

**TLDR:** HTML to Markdown conversion strips presentation markup while preserving document structure. It typically reduces page size by 90 percent or more, which is why it has become the standard input format for feeding web content to language models.

**HTML to Markdown** conversion rewrites a web page into a lightweight text format that keeps headings, lists, links, and emphasis while discarding styling, scripts, and layout containers. The practice existed for years as a documentation convenience. It became infrastructure when language models made token count a direct cost.

### Why Conversion Matters for LLMs:

1. **Token economics**: Markup consumes tokens that carry no meaning. Class names, inline styles, and nested containers are pure overhead in a prompt.
2. **Context limits**: A page that exceeds the model’s context window as HTML often fits comfortably as Markdown.
3. **Signal clarity**: Models attend to content more reliably when it is not buried in attributes and nesting.
4. **Structure retention**: Unlike plain text extraction, Markdown keeps heading hierarchy and list grouping, which carry real meaning.

The reduction is substantial. A typical article page of 180 KB of HTML converts to roughly 8 to 12 KB of Markdown. At scale, that difference determines whether a retrieval pipeline is affordable.

### What Maps Cleanly:

HTML elementMarkdown outputHeading levels 1 to 6One to six hash charactersParagraphBlank line separated textStrong and boldDouble asterisksEmphasis and italicSingle asterisksUnordered listHyphen prefixed linesOrdered listNumbered linesAnchorBracketed text with parenthesized URLImageExclamation mark, alt text, URLInline codeSingle backticksPreformatted blockTriple backtick fenceBlockquoteGreater than prefix
### What Converts Badly:

**Complex tables.** Markdown tables cannot express merged cells, nested tables, or multi row headers. Converters either flatten the structure and lose relationships, or emit raw markup that defeats the purpose of converting.

**Forms and interactive elements.** Inputs, selects, and buttons have no Markdown equivalent and are usually dropped. If the page’s value was in the form, the conversion destroys it.

**Layout carrying meaning.** Multi column comparisons and side by side panels become sequential text, and the visual relationship that made them legible disappears.

**Custom components.** Tabs, accordions, and modals flatten into undifferentiated content, often surfacing text that was hidden in the rendered page.

### Conversion in Practice:

```
import httpx
from markdownify import markdownify
from readability import Document

def page_to_markdown(url):
    html = httpx.get(url, timeout=20).text

    # Isolate main content before converting
    article = Document(html).summary()

    return markdownify(
        article,
        heading_style="ATX",
        strip=["script", "style", "nav", "footer", "form"]
    )
```

The content isolation step is what separates a usable result from a poor one. Converting a full page yields Markdown containing the entire navigation menu, cookie banner, and footer sitemap. Extracting the main content first, through [boilerplate removal](/glossary/boilerplate-removal), produces output that is both smaller and more useful.

### Conversion Order:

The sequence of operations has a larger effect on output quality than the choice of converter library.

1. **Render if needed**: Apply [JavaScript rendering](/glossary/javascript-rendering) when content is client generated, since converting an empty shell produces an empty document.
2. **Remove boilerplate**: Strip navigation, footers, advertisements, and related content panels.
3. **Resolve URLs**: Convert relative links to absolute, or every link in the output will be broken once it leaves the page context.
4. **Convert**: Transform the cleaned fragment into Markdown.
5. **Post process**: Collapse repeated blank lines and strip residual artifacts.

### Markdown and Retrieval Pipelines:

Markdown has become the default intermediate format in retrieval augmented generation for a practical reason beyond size. Its heading structure provides natural boundaries for [document chunking](/glossary/document-chunking), so a document can be split at section boundaries rather than at arbitrary character counts. Chunks that align with headings retain coherent meaning, which measurably improves retrieval quality.

Bright Data’s [Crawl API](/products/crawl-api) and [Search and Extract](/ai/web-access) return Markdown directly, with boilerplate already removed and links resolved, which removes the conversion and cleanup stage from the pipeline entirely.

Start free trial[Start with Google](#)





 ## Trusted by 50,000+ customers worldwide



























































Welcome to the Scraping Cloud

## Maximum Control and Efficiency

 [Proxies

Premium proxy infrastructure. 100% ethically sourced IPs.

- Automated session management
- Target any city in 195 countries
- Unlimited concurrent sessions





 Proxy Services





 ](/proxy-types)

 [Unlocker

Say goodbye to blocks and CAPTCHAs with a single API.



 Unlocker





 ](/products/web-unlocker)

 [Browser

Scale dynamic scraping with built-in unblocking and proxies



 Scraping Browser





 ](/products/scraping-browser)

 [Functions

Run your scrapers as fully-hosted serverless functions.



 Functions





 ](/products/web-scraper/functions)

 [Scrapers

Extract parsed data on-demand with dedicated scraper APIs.



 Scrapers API





 ](/products/web-scraper)

 [Datasets

Get fresh, validated datasets from any public website.



 Datasets





 ](/products/datasets)

 [SERP API

Quick and easy search engine scraping on demand



 SERP API





 ](/products/serp-api)







### Ready to get started?

Start free trial
