Migrating from to markdown to Turndown

From version 4, to-markdown will be renamed to Turndown, and will include a new API. This guide aims to take you through some of the changes.

Basics

First of all, Turndown uses the constructor pattern rather than just a single function.

Before

var toMarkdown = require('to-markdown') // for Node.js
var md = toMarkdown(stringOfHTML, options)

After

var TurndownService = require('turndown') // for Node.js
var turndownService = new TurndownService(options)
var md = turndownService.turndown(stringOfHTML)

Handling Non-markdown Elements

Secondly, the biggest difference in behaviour is how non-markdown elements are handled. to-markdown kept these elements and passed the outer HTML to the markdown output. By default, Turndown will just output the element's text content. This is configurable with the defaultReplacement option. For example, to restore the old behaviour (keep non-markdown elements and add some spacing if they are block):

var turndownService = new TurndownService({
  defaultReplacement: function (innerHTML, node) {
    return node.isBlock ? '\n\n' + node.outerHTML + '\n\n' : node.outerHTML
  }
})

Extending with Rules

to-markdown used the converters option to customise the behaviour. Converters have been rename to rules, and the converters options has been removed in favour of the addRule method.

Before

var md = toMarkdown(stringOfHTML, {
  converters: [{
    filter: ['del', 's', 'strike'],
    replacement: function (content) {
      return '~' + content + '~'
    }
  }]
})

After

var turndownService = new TurndownService()
turndownService.addRule('strikethrough', {
  filter: ['del', 's', 'strike'],
  replacement: function (content) {
    return '~' + content + '~'
  }
})
turndownService.turndown(stringOfHTML)

GitHub Flavoured Markdown

GitHub Flavoured Markdown extensions have moved to a plugin: https://github.com/domchristie/turndown-plugin-gfm.

Before

var md = toMarkdown(stringOfHTML, { gfm: true })

After

var gfm = require('turndown-plugin-gfm').gfm
var turndownService = new TurndownService()
turndownService.use(gfm)
turndownService.turndown(stringOfHTML)