.NET 9 · .NET 10 · built on z3l.FastHtmlParser

HTML to Markdown in microseconds

A fast HTML to Markdown converter for .NET: for a language model, a search index, a note to keep. Enter an address: the server loads the page and converts it with HtmlToMarkdown.Convert.

Try:
A part:


      

One call from HTML to Markdown

A static method, a string in, a string out. The result is never null.

  • 1
    Absolute linksGive the address of the page, and every link and image is written as a browser would follow it.
  • 2
    Less for a language model to readLeave the links, the images or both out: the text and its structure stay.
  • 3
    A part of the pageThe parser comes with the package: pick the article or a table with a CSS selector or XPath and convert only that.
  • 4
    No surprisesNo dependencies but the parser, no reflection, trimming and Native AOT compatible, thread-safe.
$dotnet add package z3l.FastHtmlParser.HtmlToMarkdown
using z3l.FastHtmlParser;

string markdown = HtmlToMarkdown.Convert(html);

// with the address of the page the links and images are absolute
string page = HtmlToMarkdown.Convert(html, "https://example.com/blog/post");

// only the text and its structure
string text = HtmlToMarkdown.Convert(html,
    options: new MarkdownOptions { Links = false, Images = false });

// a part of the page: the parser comes with the package
var doc = new HtmlParser(html, "https://example.com/blog/post");
string? article = doc.CssFirst("article").Markdown();
string? specs = doc.CssFirst("table.specs").Markdown();

Markdown that renders as the page reads

On every test page the Markdown, rendered back to HTML, has the same text, links, images, headings and list items as the page itself. CommonMark with the GitHub tables, strikethrough and task lists.

Tables

A table of data becomes a GitHub table: colspan and rowspan keep the columns in place, and a table without a heading row gets an empty one. A table that only lays out a page is written as the blocks in its cells.

Lists as they are nested

Bulleted and numbered lists at any depth, numbered from their start; task lists with checkboxes; definition lists. Two lists in a row get different markers, so that Markdown does not merge them.

Code with its language

<pre> becomes a fenced block with the language from class="language-…", its lines untouched. The fence is longer than any run of backticks inside.

Links and images

Absolute when the page URL is given, with their titles. An image that a script loads on scroll is taken from data-src; a link without an address or with a script is written as its text.

Escaped only where needed

snake_case, 2 * 3, [1] and AT&T stay as they are. A backslash appears only where Markdown would read the text as its own: *text*, a line that starts with #, - or 1.

Linear time on any markup

One pass over the parsed tags, no object per tag. A hostile page, 100,000 quotes inside each other or a table in every cell, takes milliseconds, and the result stays in proportion to the page.

HTML, the page is https://example.com/

<h2>Release <code>1.6</code></h2>
<p><b>Note:</b>snake_case and 2 * 3 stay as they are.</p>
<ul>
  <li><input type="checkbox" checked> Tables
    <ul><li>colspan and rowspan</li></ul>
  </li>
  <li><input type="checkbox"> Footnotes</li>
</ul>
<table>
  <tr><th>Page</th><th>Time</th></tr>
  <tr><td><a href="/books">Books</a></td><td>114 μs</td></tr>
</table>
<pre><code class="language-csharp">var markdown = doc.Markdown();</code></pre>

Markdown

## Release `1.6`

**Note:**<!---->snake_case and 2 * 3 stay as they are.

- [x] Tables
  - colspan and rowspan
- [ ] Footnotes

| Page | Time |
| --- | --- |
| [Books](https://example.com/books) | 114 μs |

```csharp
var markdown = doc.Markdown();
```

What it is not. It converts the HTML it is given: it does not run JavaScript and does not guess which part of a page is the article. Only what a browser shows is written: head, script, style, comments, svg and form controls are left out. A list inside a table cell is written in one line, because a cell of a Markdown table cannot hold blocks.

Benchmarks on real pages

From the HTML string to the Markdown string, parsing included. BenchmarkDotNet, .NET 10, AMD Ryzen 7 3800X. Shorter is better.

Time

Memory allocated

ReverseMarkdown 6.3.0 and Html2Markdown 8.1.2 build an HtmlAgilityPack document first. html-to-markdown 3.7.2 is a Rust library called through its .NET binding; the memory it takes in native code is not in these numbers. Html2Markdown leaves the tags it does not know in its result as HTML. The code and all the numbers: benchmarks/README.md.

Free for most, one price for the rest

The license of FastHtmlParser: free for individuals and for organizations under USD 1M of annual revenue and under 100 people, commercial use included. Larger organizations pay USD 1,000 once, for every z3l library.

See the pricing Read the license

Questions

I already use z3l.FastHtmlParser. Do I need this package?

No. The converter is a part of the parser: doc.Markdown(), tag.Markdown() and HtmlText.ToMarkdown(html). This package is the parser with one more method, HtmlToMarkdown.Convert, for those who look for a converter. The two can be installed together.

How do I get the article without the menu and the footer?

Pick it: doc.CssFirst("article").Markdown(), or main, or the selector of the block on your site. The converter does not guess what the main content is. Try it above: load a page and enter a selector.

Which Markdown does it write?

CommonMark with the GitHub tables, strikethrough and task lists. Subscript, superscript and a line break inside a table cell are written as HTML tags, which Markdown allows. Emphasis that Markdown would not take for emphasis, as in **Note:**text, gets an empty HTML comment next to it, so that it renders as on the page.

Does it run JavaScript?

No. It converts the HTML you have. For a page that builds itself in the browser, take the HTML from a headless browser first.

Is there a version for Python, JavaScript or Go?

FastHtmlParser has ports to ten languages, but the Markdown converter is in the .NET library only for now.

What does this demo do with the pages I load?

The server loads the page, converts it and keeps the parsed page in memory for 20 minutes, so that you can change the options without loading it again; nothing is written to disk or logged. Only public http / https addresses are loaded, up to 5 MB.

Do I need a commercial license?

Only if your organization, together with its affiliates, has USD 1,000,000 or more in annual revenue, or 100 or more employees and contractors. Everyone else uses it free, including in commercial products.