HTML to Markdown Converter

2.0.0 · active · verified Sun Apr 19

node-html-markdown is a high-performance, cross-platform library designed for converting HTML content into Markdown, compatible with both Node.js and browser environments. The current stable version is 2.0.0. The library's primary focus is on speed, with benchmarks indicating significantly faster conversion rates compared to popular alternatives like Turndown. Additionally, it emphasizes generating human-readable Markdown output by producing clean, concise results with consistent spacing, aiming to avoid common formatting issues such as excessive line breaks. While it does not adhere to a rigid release schedule, the project is actively maintained, with regular updates that have historically included features like table support and fixes for browser compatibility, ensuring its reliability for converting large volumes of HTML data.

Warnings

breaking Version 2.0.0 introduces a breaking change by explicitly denying special handling for certain elements that should not be present inside code blocks. This can affect how HTML within `<pre><code>` tags is rendered.
Fix: Review HTML input for elements inside code blocks that might have previously been implicitly handled. Adjust HTML or use custom translators if specific parsing behavior for these elements is desired within code blocks.
gotcha The `NodeHtmlMarkdown` instance performs better when reused for multiple conversions. Instantiating a new converter for every conversion carries an overhead that can impact performance, especially with large volumes of data.
Fix: Always create a single `new NodeHtmlMarkdown()` instance and reuse it for all subsequent `translate()` calls in performance-critical applications or when converting many HTML strings.
gotcha For browser environments, the `preferNativeParser` option defaults to `false`. Setting it to `true` can leverage the native `DOMParser` for potentially better performance and compatibility.
Fix: When running in a browser, initialize `NodeHtmlMarkdown` with `{ preferNativeParser: true }` in the options object to utilize the browser's native HTML parsing capabilities.
breaking Version 2.0.0 explicitly requires Node.js version 20.0.0 or higher. Running on older Node.js versions will result in runtime errors or unexpected behavior.
Fix: Ensure your Node.js environment is upgraded to version 20.0.0 or newer. Check your `package.json` engines field and update CI/CD configurations accordingly.

Install

npm install node-html-markdown npm
yarn add node-html-markdown yarn
pnpm add node-html-markdown pnpm

Imports

NodeHtmlMarkdown
wrong:
```
const NodeHtmlMarkdown = require('node-html-markdown')
```
correct:
```
import { NodeHtmlMarkdown } from 'node-html-markdown'
```
The library primarily targets ESM. For CJS environments, ensure proper transpilation or use a bundler.
NodeHtmlMarkdownOptions
```
import { NodeHtmlMarkdownOptions } from 'node-html-markdown'
```
Use this interface for type-safe configuration of the converter instance.
translate (static)
wrong:
```
const nhm = new NodeHtmlMarkdown(); nhm.translate(htmlString); // if only used once
```
correct:
```
NodeHtmlMarkdown.translate(htmlString)
```
For single-use conversions, the static `translate` method is convenient. For multiple conversions, create an instance for performance.

Quickstart

Demonstrates initializing a reusable instance of `NodeHtmlMarkdown` with custom options and using it to convert both single and multiple HTML strings to Markdown efficiently.

import { NodeHtmlMarkdown } from 'node-html-markdown';

// Initialize with options for a reusable instance
// Custom options can improve output or handle specific HTML structures.
const nhm = new NodeHtmlMarkdown(
  {
    codeFence: '```', // Customize code block fence (default: ```)
    bulletMarker: '-', // Use hyphens for list bullets (default: *)
    codeBlockStyle: 'fenced', // Prefer fenced code blocks (default: fenced)
    preferNativeParser: typeof window !== 'undefined' // Use native DOMParser in browsers if available
  },
  /* customTranslators (optional) */ undefined,
  /* customCodeBlockTranslators (optional) */ undefined
);

// Example HTML input to be converted
const htmlContent = `
  <h1>Welcome to my document</h1>
  <p>This is a <b>paragraph</b> with <i>some emphasis</i> and a <s>strikethrough</s> word.</p>
  <ul>
    <li>First item in a list.</li>
    <li>Second item.</li>
  </ul>
  <pre><code>function greet() {
  console.log('Hello, world!');
}
greet();</code></pre>
  <p>Check out our <a href="https://example.com/docs">documentation</a>.</p>
  <table><thead><tr><th>Header 1</th><th>Header 2</th></tr></thead><tbody><tr><td>Data 1</td><td>Data 2</td></tr></tbody></table>
`;

// Convert a single HTML string to Markdown
const markdownOutput = nhm.translate(htmlContent);
console.log('Converted Markdown Output:\n');
console.log(markdownOutput);

// The instance can be reused for multiple conversions efficiently
const anotherHtml = '<div><p>Another piece of HTML.</p></div>';
const anotherMarkdown = nhm.translate(anotherHtml);
console.log('\nAnother Converted Markdown:\n');
console.log(anotherMarkdown);

view raw JSON →