package
Fast HTML to markdown cross-compiler, compatible with both node and the browser
npm install node-html-markdownGitHub-flavored package documentation.
Across all versions, last 30 days.
4,106,149 in 30 days
Runtime metadata.
Tagged topics.
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:
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!
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.
<yarn|npm|pnpm> add node-html-markdown-----------------------------------------------------------------------------
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)
-----------------------------------------------------------------------------import { NodeHtmlMarkdown, NodeHtmlMarkdownOptions } from 'node-html-markdown'
/* ********************************************************* *
* Single use
* If using it once, you can use the static method
* ********************************************************* */
// Single file
NodeHtmlMarkdown.translate(
/* html */ `<b>hello</b>`,
/* options (optional) */ {},
/* customTranslators (optional) */ undefined,
/* customCodeBlockTranslators (optional) */ undefined
);
// Multiple files
NodeHtmlMarkdown.translate(
/* FileCollection */ {
'file1.html': `<b>hello</b>`,
'file2.html': `<b>goodbye</b>`
},
/* options (optional) */ {},
export interface NodeHtmlMarkdownOptions {
/**
* Use native window DOMParser when available
* @default false
*/
preferNativeParser: boolean,
/**
* Code block fence
* @default ```
*/
codeFence: string,
/**
* Bullet marker
* @default *
*/
bulletMarker: string,
/**
* Style for code block
* @default fence
*/
codeBlockStyle: 'indented' |
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.
Example:
const html = `<p>Hello</p><p>World</p><p>!</p>`;
const markdown = NodeHtmlMarkdown.translate(html);
console.log(markdown);
// Output:
// Hello
//
// World
//
// !This is the expected behavior and produces valid, readable Markdown. If you need tighter spacing, consider using line breaks instead of paragraphs.
<p>) create blank lines between content (standard Markdown behavior)<br>) create single line breaks with two trailing spaces (Markdown line break syntax)Example:
// Using line breaks
const 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 3The 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 newlines
const 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 newlines
const markdown2 = NodeHtmlMarkdown.translate(html, {
maxConsecutiveNewlines: 10
});
// Result preserves all 10 line breaksExample with inline elements:
const html = `<b>text</b>${'<br>'.repeat(10)}<em>something</em>`;
// Default (max 3 newlines)
NodeHtmlMarkdown.translate(html);
// Output: **text** \n \n \n_something_
// Custom (max 10 newlines)
NodeHtmlMarkdown.translate(html, { maxConsecutiveNewlines: 10 });
// Output: **text** \n \n \n \n \n \n \n \n \n \n_something_When to adjust this setting:
maxConsecutiveNewlines: 1) for more compact outputmaxConsecutiveNewlines: 10) when you need to preserve spacing from the source HTML3) for balanced, readable Markdown outputCustom translators are an advanced option to allow handling certain elements a specific way.
These can be modified via the NodeHtmlMarkdown#translators property, or added during creation.
For detail on how to use them see:
TranslatorConfigdefaultTranslatorsThe NodeHtmlMarkdown#codeBlockTranslators property is a collection of translators which handles elements within a <pre><code> block.
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:
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!
Looking to contribute? Check out our help wanted list for a good place to start!
Estimated unpacked size across 9 packages.
2.0 MB
Includes dependencies.