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

Options deprecated in version 6

Deprecated options will be removed with future major version update.

Options removed in version 6

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:

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:

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