html-to-text

What is html-to-text?

The html-to-text npm package is designed to convert HTML documents into plain text. It can handle various HTML elements, preserving the basic structure and formatting in a text-only format. This is particularly useful for extracting text from HTML emails, web pages, or any HTML content for use in text-based formats.

What are html-to-text's main functionalities?

Convert HTML to plain text

This feature allows you to convert a string of HTML into a plain text format, with options such as word wrapping.

const htmlToText = require('html-to-text');
const html = '<h1>Hello World</h1>';
const text = htmlToText.fromString(html, {
  wordwrap: 130
});
console.log(text); // Outputs: 'Hello World'

Handling of tables

This feature enables the conversion of HTML tables into a tabular text format, preserving the layout of the data.

const htmlToText = require('html-to-text');
const html = '<table><tr><td>Foo</td><td>Bar</td></tr></table>';
const text = htmlToText.fromString(html, {
  tables: true
});
console.log(text); // Outputs a text representation of the table

Handling of lists

This feature converts HTML lists into plain text, with customizable prefixes for list items.

const htmlToText = require('html-to-text');
const html = '<ul><li>Item 1</li><li>Item 2</li></ul>';
const text = htmlToText.fromString(html, {
  unorderedListItemPrefix: '- '
});
console.log(text); // Outputs: '- Item 1\n- Item 2'

Handling of hyperlinks

This feature allows for the conversion of hyperlinks into plain text, with options to hide or display the URL based on the link text.

const htmlToText = require('html-to-text');
const html = '<a href='https://example.com'>Example</a>';
const text = htmlToText.fromString(html, {
  hideLinkHrefIfSameAsText: true
});
console.log(text); // Outputs: 'Example'

Other packages similar to html-to-text

turndown

Turndown is an HTML to Markdown converter that allows users to convert HTML content to Markdown format. It is different from html-to-text as it focuses on Markdown output rather than plain text.

html2plaintext

html2plaintext is another package that converts HTML to plain text. It aims to produce human-readable text similar to what a browser would render, but it may have different parsing and formatting options compared to html-to-text.

html-to-text-cli

html-to-text-cli is a command-line interface for converting HTML to plain text. While it uses the html-to-text package under the hood, it is specifically designed for CLI usage and may offer a different user experience.

README

html-to-text

Advanced converter that parses HTML and returns beautiful text.

Features

• Inline and block-level tags.
• Tables with colspans and rowspans.
• Links with both text and href.
• Word wrapping.
• Unicode support.
• Plenty of customization options.

Changelog

Available here: CHANGELOG.md

Version 6 contains a ton of changes, so it worth to take a look.

Version 7 contains an important change for custom formatters.

Installation

npm install html-to-text

Or when you want to use it as command line interface it is recommended to install it globally via

npm install html-to-text -g

Usage

const { htmlToText } = require('html-to-text');

const html = '<h1>Hello World</h1>';
const text = htmlToText(html, {
  wordwrap: 130
});
console.log(text); // Hello World

Options

General options

Option	Default	Description
baseElement	'body'	The tag(s) whose text content will be captured from the html and added to the resulting text output. Single element or an array of elements can be specified, each as a single tag name with optional css class and id parameters e.g. ['p.class1.class2#id1#id2', 'p.class1.class2#id1#id2'].
decodeOptions	{ isAttributeValue: false, strict: false }	Text decoding options given to he.decode. For more informations see the he module.
formatters	{}	An object with custom formatting functions for specific elements (see Override formatting section below).
limits		Describes how to limit the output text in case of large HTML documents.
limits.ellipsis	'...'	A string to insert in place of skipped content.
limits.maxChildNodes	undefined	Maximum number of child nodes of a single node to be added to the output. Unlimited if undefined.
limits.maxDepth	undefined	Stop looking for nodes to add to the output below this depth in the DOM tree. Unlimited if undefined.
limits.maxInputLength	16_777_216	If the input string is longer than this value - it will be truncated and a message will be sent to stderr. Ellipsis is not used in this case. Unlimited if undefined.
longWordSplit		Describes how to wrap long words.
longWordSplit.wrapCharacters	[]	An array containing the characters that may be wrapped on. Checked in order, search stops once line length requirement can be met.
longWordSplit.forceWrapOnLimit	false	Break long words at the line length limit in case no better wrap opportunities found.
preserveNewlines	false	By default, any newlines \n from the input HTML are collapsed into space as any other HTML whitespace characters. If true, these newlines will be preserved in the output. This is only useful when input HTML carries some plain text formatting instead of proper tags.
returnDomByDefault	true	Convert the entire document if we don't find the tag defined in baseElement.
tables	[]	Allows to select certain tables by the class or id attribute from the HTML document. This is necessary because the majority of HTML E-Mails uses a table based layout. Prefix your table selectors with an . for the class and with a # for the id attribute. All other tables are ignored. You can assign true to this attribute to select all tables.
tags		Describes how different tags should be formatted. See Tags section below.
whitespaceCharacters	' \t\r\n\f\u200b'	A string of characters that are recognized as HTML whitespace. Default value uses the set of characters defined in HTML4 standard. (It includes Zero-width space compared to living standard.)
wordwrap	80	After how many chars a line break should follow. Set to null or false to disable word-wrapping.

Options deprecated in version 6

Old option	Instead use
hideLinkHrefIfSameAsText	tags: { 'a': { options: { hideLinkHrefIfSameAsText: true } } }
ignoreHref	tags: { 'a': { options: { ignoreHref: true } } }
ignoreImage	tags: { 'img': { format: 'skip' } }
linkHrefBaseUrl	tags: { 'a': { options: { baseUrl: 'https://example.com' } }, 'img': { options: { baseUrl: 'https://example.com' } } }
noAnchorUrl	tags: { 'a': { options: { noAnchorUrl: true } } }
noLinkBrackets	tags: { 'a': { options: { noLinkBrackets: true } } }
singleNewLineParagraphs	tags: { 'p': { options: { leadingLineBreaks: 1, trailingLineBreaks: 1 } }, 'pre': { options: { leadingLineBreaks: 1, trailingLineBreaks: 1 } } }
unorderedListItemPrefix	tags: { 'ul': { options: { itemPrefix: ' * ' } } }
uppercaseHeadings	tags: { 'h1': { options: { uppercase: false } }, ... 'table': { options: { uppercaseHeaderCells: false } } }

Deprecated options will be removed with future major version update.

Options removed in version 6

Old option	Description
format	The way formatters are written has changed completely. New formatters have to be added to the formatters option, old ones can not be reused without rewrite. See new instructions below.

Tags

Example for tag-specific options:

const { htmlToText } = require('html-to-text');

const html = '<a href="/page.html">Page</a>';
const text = htmlToText(html, {
  tags: {
    'a': { options: { baseUrl: 'https://example.com' } },
    'figure': { format: 'block' }
  }
});
console.log(text); // Page [https://example.com/page.html]

For new tags you have to specify the format value. For tags listed below you can skip it and only provide options. (Valid options listed in the next table.)

By default there are following tag to format assignments:

Tag name	Default format	Notes
''	inline	Catch-all default for unknown tags.
a	anchor
article	block
aside	block
blockquote	blockquote
br	lineBreak
div	block
footer	block
form	block
h1	heading
h2	heading
h3	heading
h4	heading
h5	heading
h6	heading
header	block
hr	horizontalLine
img	image
main	block
nav	block
ol	orderedList
p	paragraph
pre	pre
table	table	there is also dataTable format. Using it will be equivalent to setting tables to true. tables option might be deprecated in the future.
ul	unorderedList
wbr	wbr

More formats also available for use:

• skip - as the name implies it skips the given tag with it's contents without printing anything.

Format options are specified for each tag indepentently:

Option	Default	Applies to	Description
leadingLineBreaks	1, 2 or 3	all block-level formatters	Number of line breaks to separate previous block from this one. Note that N+1 line breaks are needed to make N empty lines.
trailingLineBreaks	1 or 2	all block-level formatters	Number of line breaks to separate this block from the next one. Note that N+1 line breaks are needed to make N empty lines.
baseUrl	null	anchor, image	Server host for link href attributes and image src attributes relative to the root (the ones that start with /). For example, with baseUrl = 'http://asdf.com' and <a href='/dir/subdir'>...</a> the link in the text will be http://asdf.com/dir/subdir. Keep in mind that baseUrl should not end with a /.
hideLinkHrefIfSameAsText	false	anchor	By default links are translated in the following way: <a href='link'>text</a> => becomes => text [link]. If this option is set to true and link and text are the same, [link] will be omitted and only text will be present.
ignoreHref	false	anchor	Ignore all links. Only process internal text of anchor tags.
noAnchorUrl	true	anchor	Ignore anchor links (where href='#...').
noLinkBrackets	false	anchor	Don't print brackets around links.
itemPrefix	' * '	unorderedList	String prefix for each list item.
uppercase	true	heading	By default, headings (<h1>, <h2>, etc) are uppercased. Set this to false to leave headings as they are.
length	undefined	horizontalLine	Length of the line. If undefined then wordwrap value is used. Falls back to 40 if that's also disabled.
trimEmptyLines	true	blockquote	Trim empty lines from blockquote. While empty lines should be preserved in HTML, space-saving behavior is chosen as default for convenience.
uppercaseHeaderCells	true	table, dataTable	By default, heading cells (<th>) are uppercased. Set this to false to leave heading cells as they are.
maxColumnWidth	60	table, dataTable	Data table cell content will be wrapped to fit this width instead of global wordwrap limit. Set this to undefined in order to fall back to wordwrap limit.
colSpacing	3	table, dataTable	Number of spaces between data table columns.
rowSpacing	0	table, dataTable	Number of empty lines between data table rows.

Override formatting

This is significantly changed in version 6.

formatters option is an object that holds formatting functions. They can be assigned to format different tags by key in the tags option.

Each formatter is a function of four arguments that returns nothing. Arguments are:

• elem - the HTML element to be processed by this formatter;
• walk - recursive function to process the children of this element. Called as walk(elem.children, builder);
• builder - BlockTextBuilder object. Manipulate this object state to build the output text;
• formatOptions - options that are specified for a tag, along with this formatter (Note: if you need general html-to-text options - they are accessible via builder.options).

Custom formatter example:

const { htmlToText } = require('html-to-text');

const html = '<foo>Hello World</foo>';
const text = htmlToText(html, {
  formatters: {
    // Create a formatter.
    'fooBlockFormatter': function (elem, walk, builder, formatOptions) {
      builder.openBlock({ leadingLineBreaks: formatOptions.leadingLineBreaks || 1 });
      walk(elem.children, builder);
      builder.addInline('!');
      builder.closeBlock({ trailingLineBreaks: formatOptions.trailingLineBreaks || 1 });
    }
  },
  tags: {
    // Assign it to `foo` tags.
    'foo': {
      format: 'fooBlockFormatter',
      options: { leadingLineBreaks: 1, trailingLineBreaks: 1 }
    }
  }
});
console.log(text); // Hello World!

Refer to built-in formatters for more examples.

Refer to BlockTextBuilder for available functions and arguments.

Note: BlockTextBuilder got some important changes in the version 7. Positional arguments are deprecated and formatters written for the version 6 have to be updated accordingly in order to keep working after next major update.

Command Line Interface

It is possible to use html-to-text as command line interface. This allows an easy validation of your generated text and the integration in other systems that does not run on node.js.

html-to-text uses stdin and stdout for data in and output. So you can use html-to-text the following way:

cat example/test.html | html-to-text > test.txt

There also all options available as described above. You can use them like this:

cat example/test.html | html-to-text --tables=#invoice,.address --wordwrap=100 > test.txt

The tables option has to be declared as comma separated list without whitespaces.

Example

• Input text: test.html
• Output text: test.txt

Contributors

• @mlegenhausen - creator;
• @KillyMXI - maintainer since 2020;
• Everyone else who added something to the tool or helped us shaping it via issues and PRs.

License

MIT License