NHM is a fast HTML to markdown converter, compatible with both node and the browser.
It was built with the following two goals in mind:
1. Speed
We had a need to convert gigabytes of HTML daily very quickly. All libraries we found were too slow with node.
We considered using a low-level language but decided to attempt to write something that would squeeze every bit
of performance out of the JIT that we could. The end result was fast enough to make the cut!
2. Human Readability
The other libraries we tested produced output that would break in numerous conditions and produced output with many
repeating linefeeds, etc. Generally speaking, outside of a markdown viewer, the result was not easy to read.
We took the approach of producing a clean, concise result with consistent spacing rules.
Install
<yarn|npm|pnpm> add node-html-markdown
Benchmarks
-----------------------------------------------------------------------------Estimated processing times (fastest to slowest): [node-html-markdown (reused instance)] 100 kB: 17ms 1 MB: 176ms 50 MB: 8.80sec 1 GB: 3min, 0sec 50 GB: 2hr, 30min, 14sec [turndown (reused instance)] 100 kB: 27ms 1 MB: 280ms 50 MB: 13.98sec 1 GB: 4min, 46sec 50 GB: 3hr, 58min, 35sec-----------------------------------------------------------------------------Speed comparison - node-html-markdown (reused instance) is: 1.02 times as fast as node-html-markdown 1.57 times as fast as turndown 1.59 times as fast as turndown (reused instance)-----------------------------------------------------------------------------
Usage
import { NodeHtmlMarkdown, NodeHtmlMarkdownOptions } from 'node-html-markdown'/* ********************************************************* * * Single use * If using it once, you can use the static method * ********************************************************* */// Single fileNodeHtmlMarkdown.translate( /* html */ `<b>hello</b>`, /* options (optional) */ {}, /* customTranslators (optional) */ undefined, /* customCodeBlockTranslators (optional) */ undefined);// Multiple filesNodeHtmlMarkdown.translate( /* FileCollection */ { 'file1.html': `<b>hello</b>`, 'file2.html': `<b>goodbye</b>` }, /* options (optional) */ {},
In standard Markdown, paragraphs are separated by blank lines. This library follows this convention, so HTML block elements like <p>, <div>, <h1>, etc. are surrounded by blank lines in the output.
This is the expected behavior and produces valid, readable Markdown. If you need tighter spacing, consider using line breaks instead of paragraphs.
Line Breaks vs Paragraphs
Paragraphs (<p>) create blank lines between content (standard Markdown behavior)
Line breaks (<br>) create single line breaks with two trailing spaces (Markdown line break syntax)
Example:
// Using line breaksconst html = `<p>Line 1<br>Line 2<br>Line 3</p>`;const markdown = NodeHtmlMarkdown.translate(html);console.log(markdown);// Output:// Line 1// Line 2// Line 3
Controlling Consecutive Newlines
The maxConsecutiveNewlines option (default: 3) limits how many consecutive newlines appear in the output. This helps keep the Markdown clean and prevents excessive whitespace.
Example with multiple <br> tags:
// Default behavior - limits to 3 consecutive newlinesconst html = `<p>a</p>${'<br>'.repeat(10)}<p>b</p>`;const markdown = NodeHtmlMarkdown.translate(html);// Result has maximum 3 consecutive line breaks// Allow more consecutive newlinesconst markdown2 = NodeHtmlMarkdown.translate(html, { maxConsecutiveNewlines: 10});// Result preserves all 10 line breaks
The NodeHtmlMarkdown#codeBlockTranslators property is a collection of translators which handles elements within a <pre><code> block.
Further improvements
Being a performance-centric library, we're always interested in further improvements.
There are several probable routes by which we could gain substantial performance increases over the current model.
Such methods include:
Writing a custom parser
Integrating an async worker-thread based model for multi-threading
Fully replacing any remaining regex
These would be fun to implement; however, for the time being, the present library is fast enough for my purposes. That
said, I welcome discussion and any PR toward the effort of further improving performance, and I may ultimately do more
work in that capacity in the future!
Help Wanted!
Looking to contribute? Check out our help wanted list for a good place to start!