node-html-markdown

For advanced customization, you can provide custom translators to handle specific elements.

• General Elements: Can be added during instance creation via the constructor or modified via the NodeHtmlMarkdown#translators property.
• Code Blocks: Elements within <pre><code> blocks can be handled by NodeHtmlMarkdown#codeBlockTranslators.

Refer to translator.ts and config.ts in the source for detailed TranslatorConfig and the list of defaultTranslators.

The library follows standard Markdown conventions for spacing:

• Paragraphs: HTML block elements like <p>, <div>, or <h1> are surrounded by blank lines in the output.
• Line Breaks: The <br> tag creates a single line break using the Markdown line break syntax (two trailing spaces).

To control the amount of whitespace, use the maxConsecutiveNewlines option. A value of 1 creates compact output, while higher values (e.g., 10) preserve more spacing from the source HTML.

// Default behavior - limits to 3 consecutive newlines
const html = `<p>a</p>${'<br>'.repeat(10)}<p>b</p>`;
const markdown = NodeHtmlMarkdown.translate(html);

// Allow more consecutive newlines
const markdown2 = NodeHtmlMarkdown.translate(html, {
  maxConsecutiveNewlines: 10
});

You can install node-html-markdown using npm, yarn, or pnpm. It is compatible with both Node.js and browser environments.

<yarn|npm|pnpm> add node-html-markdown

The benchmark-tool package provides a simple benchmark for comparing different HTML to Markdown compilers using real-life data. You can execute the benchmark suite using the following command:

yarn run benchmark

The converter uses a translator system to map HTML elements to Markdown. You can extend or override the defaultTranslators by providing a TranslatorConfigObject.

Translators can define:

• prefix: Text to prepend to the element's content.
• postfix: Text to append to the element's content.
• content: Static content to replace the element with.
• surroundingNewlines: Number of newlines to add around the element.
• noEscape: Whether to skip escaping the content.
• preserveWhitespace: Whether to preserve whitespace.
• recurse: Whether to process child nodes.
• childTranslators: A nested TranslatorConfigObject for elements inside the current one.
• postprocess: A function to transform the resulting string after translation.

If you only need to perform a single conversion, use the static NodeHtmlMarkdown.translate method. You can pass a single HTML string or a FileCollection object containing multiple files.

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

// 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) */ {},
  /* customTranslators (optional) */ undefined,
  /* customCodeBlockTranslators (optional) */ undefined
);

For better performance when performing multiple conversions, create an instance of NodeHtmlMarkdown. Reusing an instance is faster than calling the static method repeatedly.

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

const nhm = new NodeHtmlMarkdown(
  /* options (optional) */ {},
  /* customTransformers (optional) */ undefined,
  /* customCodeBlockTranslators (optional) */ undefined
);

// Single file
hm.translate(/* html */ `<b>hello</b>`);

// Multiple Files
hm.translate(
  /* FileCollection */ { 
    'file1.html': `<b>hello</b>`, 
    'file2.html': `<b>goodbye</b>` 
  }
);

The NodeHtmlMarkdownOptions interface allows you to customize how HTML is converted to Markdown. You can control delimiters for emphasis, list indentation, code block styles, and how specific HTML elements are handled (e.g., ignoring certain tags or treating others as block elements). It also provides advanced control over newline handling, escaping patterns, and link formatting.

const options: NodeHtmlMarkdownOptions = {
  codeFence: '```',
  bulletMarker: '-',
  indent: '    ',
  codeBlockStyle: 'fenced',
  maxConsecutiveNewlines: 2,
  useLinkReferenceDefinitions: true
};

The primary entrypoint for converting HTML to Markdown is the NodeHtmlMarkdown class. It is used to process HTML strings or files into Markdown format based on provided options.

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

const converter = new NodeHtmlMarkdown();
const markdown = converter.translate('<h1>Hello World</h1>');