Turndown

Turndown uses rules to transform HTML elements into Markdown. A rule consists of two parts:

1. filter: Determines which elements are selected. It can be a string (tag name), an array of strings, or a function that returns a boolean based on the node and current options.
2. replacement: A function that determines the Markdown output. It receives the node's content, the node itself, and the options object.

Rule Precedence

Turndown picks the first matching rule based on this order:

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

// Example of a custom rule
{
  filter: ['em', 'i'],
  replacement: function (content, node, options) {
    return options.emDelimiter + content + options.emDelimiter
  }
}

To convert HTML to Markdown, instantiate TurndownService and call the .turndown() method. You can pass an HTML string or a DOM node (element, document, or document fragment) as input.

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

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

// Using a DOM node
var markdown = turndownService.turndown(document.getElementById('content'))

You can install Turndown via npm for Node.js environments or include it directly in the browser using a <script> tag.

npm install turndown

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

Options can be passed to the TurndownService constructor during instantiation to customize the Markdown output style.

var turndownService = new TurndownService({ option: 'value' })

Use keep(filter) to specify which elements should be rendered as raw HTML in the Markdown output instead of being converted. The filter parameter works like a rule filter. keep returns the TurndownService instance for chaining. Note that keep filters can be overridden by standard CommonMark rules or custom added rules.

turndownService.keep(['del', 'ins'])
turndownService.turndown('<p>Hello <del>world</del><ins>World</ins></p>') // 'Hello <del>world</del><ins>World</ins>'

Use addRule to extend Turndown's behavior. A rule is an object containing a filter (to select elements) and a replacement function (to define the Markdown output). addRule returns the TurndownService instance for chaining.

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

Use remove(filter) to specify elements that should be completely removed (converted to an empty string) from the output. The filter parameter works like a rule filter. remove returns the TurndownService instance for chaining. Note that remove filters can be overridden by keep filters, standard CommonMark rules, or custom added rules.

turndownService.remove('del')
turndownService.turndown('<p>Hello <del>world</del><ins>World</ins></p>') // 'Hello World'

A plugin is a function that is called with the TurndownService instance. You can apply one or multiple plugins using the use method. use returns the TurndownService instance for chaining.

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

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

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

Standard configuration options for TurndownService.

| Option | Valid values | Default |
| :--- | :--- | :--- |
| `headingStyle` | `setext` or `atx` | `setext` |
| `hr` | Any [Thematic break](http://spec.commonmark.org/0.27/#thematic-breaks) | `* * *` |
| `bulletListMarker` | `-`, `+`, or `*` | `*` |
| `codeBlockStyle` | `indented` or `fenced` | `indented` |
| `fence` | ` ``` ` or `~~~` | ` ``` ` |
| `emDelimiter` | `_` or `*` | `_` |
| `strongDelimiter` | `**` or `__` | `**` |
| `linkStyle` | `inlined` or `referenced` | `inlined` |
| `linkReferenceStyle` | `full`, `collapsed`, or `shortcut` | `full` |
| `preformattedCode` | `false` or `true` | `false` |

Advanced configuration options that allow overriding rule replacement logic.

| Option | Valid values | Default |
| :--- | :--- | :--- |
| `blankReplacement` | rule replacement function | See **Special Rules** below |
| `keepReplacement` | rule replacement function | See **Special Rules** below |
| `defaultReplacement` | rule replacement function | See **Special Rules** below |