repository·master·Indexed 23 days ago
https://github.com/html-to-text/node-html-to-textAn advanced Node.js library and CLI for converting HTML to plain text or Markdown. It features a customizable selector system for element formatting, support for tables, word wrapping, and Unicode. The package includes a CLI tool (@html-to/text-cli) that supports JSON configuration files, predefined presets (human and machine), and terminal pipes, as well as a specialized Markdown converter (@html-to/md).
The html-to-text library is an advanced converter that parses HTML and returns formatted text. Key features include:
colspans and rowspans.href attributes.@html-to/text-cli.@html-to/md is an advanced converter designed to parse HTML and return Markdown. It is highly customizable, following a similar pattern to html-to-text, but produces a Markdown output format that is compatible and reusable across other systems.The selectors option is an array of objects that acts like a loose approximation of a stylesheet. Each object defines a selector (CSS-like) and a format (the formatter to use).
Selector Rules:
Supported Selector Syntax:
* (universal), tag names (div), .class, #id, [attribute], [attribute=value] (including operators and case modifiers).+ and >.:empty, :first-child, :last-child, :only-child, :any-link.const { convert } = require('html-to-text');
const html = '<a href="/page.html">Page</a><a href="!#" class="button">Action</a>';
const text = convert(html, {
selectors: [
{ selector: 'a', options: { baseUrl: 'https://example.com' } },
{ selector: 'a.button', format: 'skip' }
]
});
console.log(text); // Page [https://example.com/page.html]Install the @html-to/text-cli package globally via npm to use the html-to-text command in your terminal.
Important Note on Name Collisions:
html-to-text package are uninstalled globally to avoid command conflicts.@html-to/text-cli to avoid confusion with an unrelated abandoned CLI package.npm i -g @html-to/text-cliThe CLI converts HTML from stdin to plain text on stdout. You can pass converter options as command-line arguments.
Bash/Linux/macOS usage:
cat ./input.html | html-to-text [commands...] [keys and values...] > ./output.txtPowerShell usage:
In PowerShell, use the .cmd wrapper (html-to-text.cmd) because the .ps1 wrapper may not work correctly with stdin.
Get-Content .\input.html | html-to-text.cmd [commands...] [keys and values...] > .\output.txtInstall the html-to-text package using npm to use the advanced HTML-to-text converter in your projects.
npm install html-to-texteslint.config.mjs). The configuration enforces strict coding standards, including JSDoc requirements, import ordering, and specific file naming conventions. It applies different rules based on file patterns (e.g., CLI packages, examples, tests, and Rollup configs).The CLI uses a specific syntax for passing options:
html-to-text engine. For example, an argument like --word-wrap will be passed to the engine as wordWrap.--json flag to output the result in JSON format (via the internal business logic).--merge flag to compose CLI options.The following general options are available in the options object:
| Option | Default | Description |
|---|---|---|
baseElements | Describes which parts of the input document are converted and in what order. Includes selectors (array), orderBy ('selectors' or 'occurrence'), and returnDomByDefault (boolean). | |
decodeEntities | true | Whether to decode HTML entities. |
encodeCharacters | {} | A dictionary mapping characters to escape sequences. |
formatters | {} | Object containing custom formatting functions. |
limits | Limits output for large documents. Includes ellipsis (string), maxBaseElements (number), maxChildNodes (number), maxDepth (number), and maxInputLength (number). | |
longWordSplit | Controls wrapping of long words. Includes wrapCharacters (array) and forceWrapOnLimit (boolean). | |
preserveNewlines | false | If true, preserves \n from input HTML instead of collapsing them into spaces. |
selectors | [] | Array of objects describing how different HTML elements should be formatted. |
whitespaceCharacters | ' \t\r\n\f\u200b' | String of characters recognized as HTML whitespace. |
wordwrap | 80 | Number of characters after which a line break follows. Set to null or false to disable. |
The @html-to/text-cli is an advanced HTML to plain text converter. It operates via standard streams: it reads HTML input from stdin and writes the resulting plain text to stdout.
All options available in the html-to-text package can be expressed as CLI arguments (except for function-based options).
Basic Usage Pattern:
cat input.html | html-to-text > output.txtIf you need to provide extra information to your custom formatters, you can pass a metadata object as the last argument to convert() or the function returned by compile(). This object is accessible within your formatter via builder.metadata.
import { compile, convert } from 'html-to-text';
// For batch use:
const compiledConvert = compile(options);
let text = compiledConvert(html, metadata);
// For single use:
let text = convert(html, options, metadata);You can define custom formatting logic by adding functions to the formatters object in your options. A custom formatter is a function with four arguments:
elem: The HTML element being processed.walk: A recursive function to process children: walk(elem.children, builder).builder: A BlockTextBuilder object used to manipulate the output state.formatOptions: Options specified for that specific tag.To use a custom formatter, assign it to a selector in the selectors array.
const { convert } = require('html-to-text');
const html = '<foo>Hello World</foo>';
const text = convert(html, {
formatters: {
'fooBlockFormatter': function (elem, walk, builder, formatOptions) {
builder.openBlock({ leadingLineBreaks: formatOptions.leadingLineBreaks || 1 });
walk(elem.children, builder);
builder.addInline('!');
builder.closeBlock({ trailingLineBreaks: formatOptions.trailingLineBreaks || 1 });
}
},
selectors: [
{
selector: 'foo',
format: 'fooBlockFormatter',
options: { leadingLineBreaks: 1, trailingLineBreaks: 1 }
}
]
});
console.log(text); // Hello World!