turndown

What is turndown?

Turndown is a library that converts HTML into Markdown. It provides a simple API to transform HTML strings into Markdown format, making it useful for applications that need to convert rich text content into a more readable and lightweight format.

What are turndown's main functionalities?

Basic HTML to Markdown Conversion

This feature allows you to convert basic HTML elements into their Markdown equivalents. In this example, an HTML heading is converted into a Markdown heading.

const TurndownService = require('turndown');
const turndownService = new TurndownService();
const markdown = turndownService.turndown('<h1>Hello World</h1>');
console.log(markdown); // # Hello World

Custom Rules

Turndown allows you to add custom rules for converting specific HTML elements. In this example, a custom rule is added to convert <del>, <s>, and <strike> tags into Markdown strikethrough syntax.

const TurndownService = require('turndown');
const turndownService = new TurndownService();
turndownService.addRule('strikethrough', {
  filter: ['del', 's', 'strike'],
  replacement: function (content) {
    return '~~' + content + '~~';
  }
});
const markdown = turndownService.turndown('<del>Deleted text</del>');
console.log(markdown); // ~~Deleted text~~

Handling Complex HTML Structures

Turndown can handle complex HTML structures and convert them into Markdown. This example demonstrates converting a nested HTML structure with headings, paragraphs, and inline formatting.

const TurndownService = require('turndown');
const turndownService = new TurndownService();
const html = '<div><h1>Title</h1><p>This is a <strong>paragraph</strong> with <em>emphasis</em>.</p></div>';
const markdown = turndownService.turndown(html);
console.log(markdown); // # Title\n\nThis is a **paragraph** with *emphasis*.

Other packages similar to turndown

showdown

Showdown is a bidirectional converter that can convert Markdown to HTML and vice versa. It offers a wide range of options and extensions for customization. Compared to Turndown, Showdown is more versatile as it supports both directions of conversion.

markdown-it

Markdown-it is a fast and flexible Markdown parser that can be extended with plugins. While it primarily focuses on converting Markdown to HTML, it can be extended to support HTML to Markdown conversion with additional plugins. It is known for its speed and extensibility.

remark

Remark is a Markdown processor powered by plugins. It can parse, transform, and compile Markdown. With the right plugins, it can also handle HTML to Markdown conversion. Remark is highly modular and customizable, making it suitable for complex transformations.

README

Turndown

Convert HTML into Markdown with JavaScript.

Installation

npm:

npm install turndown

Browser:

<script src="https://unpkg.com/turndown/dist/turndown.js"></script>

Usage

// For Node.js
var TurndownService = require('turndown')

var turndownService = new TurndownService()
var markdown = turndownService.turndown('<h1>Hello world!</h1>')

Options

Options can be passed in to the constructor on instantiation.

Option	Valid values	Default
headingStyle	setext or atx	setext
hr	Any Thematic break	* * *
bulletListMarker	-, +, or *	*
codeBlockStyle	indented or fenced	indented
fence	``` or ~~~	```
emDelimiter	_ or *	_
strongDelimiter	** or __	**
linkStyle	inlined or referenced	inlined
linkReferenceStyle	full, collapsed, or shortcut	full

Advanced Options

Option	Valid values	Default
blankReplacement	rule replacement function	See Special Rules below
keep	rule filter	See Special Rules below
remove	rule filter	See Special Rules below
defaultReplacement	rule replacement function	See Special Rules below
keepRule	rule	See Special Rules below
removeRule	rule	See Special Rules below

Methods

addRule(key, rule)

The key parameter is a unique name for the rule for easy reference. Example:

turndownService.addRule('strikethrough', {
  filter: ['del', 's', 'strike'],
  replacement: function (content) {
    return '~' + content + '~'
  }
})

See Extending with Rules below.

use(plugin|array)

Use a plugin, or an array of plugins. Example:

// Import plugins from turndown-plugin-gfm
var turndownPluginGfm = require('turndown-plugin-gfm')
var gfm = turndownPluginGfm.gfm
var tables = gfm.tables
var strikethrough = gfm.strikethrough

// Use the gfm plugin
turndownService.use(gfm)

// Use the table and strikethrough plugins only
turndownService.use([tables, strikethrough])

See Plugins below.

Extending with Rules

Turndown can be extended by adding rules. A rule is a plain JavaScript object with filter and replacement properties. For example, the rule for converting <p> elements is as follows:

{
  filter: 'p',
  replacement: function (content) {
    return '\n\n' + content + '\n\n'
  }
}

The filter selects <p> elements, and the replacement function returns the <p> contents separated by two new lines.

filter String|Array|Function

The filter property determines whether or not an element should be replaced with the rule's replacement. DOM nodes can be selected simply using a tag name or an array of tag names:

• filter: 'p' will select <p> elements
• filter: ['em', 'i'] will select <em> or <i> elements

Alternatively, the filter can be a function that returns a boolean depending on whether a given node should be replaced. The function is passed a DOM node as well as the TurndownService options. For example, the following rule selects <a> elements (with an href) when the linkStyle option is inlined:

filter: function (node, options) {
  return (
    options.linkStyle === 'inlined' &&
    node.nodeName === 'A' &&
    node.getAttribute('href')
  )
}

replacement Function

The replacement function determines how an element should be converted. It should return the Markdown string for a given node. The function is passed the node's content, the node itself, and the TurndownService options.

The following rule shows how <em> elements are converted:

rules.emphasis = {
  filter: ['em', 'i'],

  replacement: function (content, node, options) {
    return options.emDelimiter + content + options.emDelimiter
  }
}

Special Rules

Blank rule determines how to handle blank elements. It overrides every rule (even those added via addRule). A node is blank if it only contains whitespace, and it's not an <a>, <td>,<th> or a void element. Its behaviour can be customised using the blankReplacement option.

Keep rule determines how to handle the elements that should not be converted, i.e. rendered as HTML in the Markdown output. By default, it will keep <table> and plain <pre> elements. Block-level elements will be separated from surrounding content by blank lines. The keep rule filter can be customised using the keep option. To replace the rule, use the keepRule option. The keep rule may be overridden by rules added via addRule.

Remove rule determines which elements to remove altogether. By default, it removes <head>, <link>, <meta>, <script>, and <style> elements, and replaces them with an empty string. Like the keep rule, its filter can be customised using the remove option. To replace the rule, use the removeRule option. The remove rule may be overridden by rules added via addRule.

Default rule handles nodes which are not recognised by any other rule. By default, it outputs the node's text content (separated by blank lines if it is a block-level element). Its behaviour can be customised with the defaultReplacement option.

Rule Precedence

Turndown iterates over the set of rules, and picks the first one that matches satifies the filter. The following list describes the order of precedence:

1. Blank rule
2. Added rules (optional)
3. Keep rule
4. Remove rule
5. Commonmark rules
6. Default rule

Plugins

The plugin API provides a convenient way for developers to apply multiple extensions. A plugin is just a function that is called with the TurndownService instance.

License

turndown is copyright © 2017+ Dom Christie and released under the MIT license.