Skip to main content

​
Overview

Turndown is the successor to the to-markdown library. The project was renamed to better reflect its purpose and to provide a fresh start for ongoing development.
The to-markdown package has been deprecated in favor of Turndown. All new projects should use Turndown, and existing projects are encouraged to migrate.

​
Why Migrate?

Turndown offers several improvements over to-markdown:
  • Active maintenance - Regular updates and bug fixes
  • Better API - More intuitive method names and options
  • Plugin system - Extensible architecture for adding features
  • Improved performance - Optimized HTML parsing and conversion
  • Better documentation - Comprehensive guides and examples
  • TypeScript support - Type definitions for better IDE support

​
Quick Migration Steps

1

Update package dependency

Replace to-markdown with turndown in your package.json:
npm uninstall to-markdown
npm install turndown
2

Update require/import statements

Change your module imports:
// Before (to-markdown)
var toMarkdown = require('to-markdown')

// After (Turndown)
var TurndownService = require('turndown')
3

Update instantiation

Create a Turndown service instance:
// Before (to-markdown)
var markdown = toMarkdown('<h1>Hello</h1>')

// After (Turndown)
var turndownService = new TurndownService()
var markdown = turndownService.turndown('<h1>Hello</h1>')
4

Update method calls

Review and update any custom rules or method calls based on the breaking changes below.

​
Breaking Changes

​
1. Constructor Required

to-markdown was a function that could be called directly. Turndown requires instantiation: 
var toMarkdown = require('to-markdown')
var markdown = toMarkdown('<p>Hello world</p>')

​
2. Method Naming

Several methods have been renamed for consistency:
to-markdownTurndownDescription
N/A (direct call)turndown()Convert HTML to Markdown
toMarkdown.addRule()addRule()Add a custom rule
toMarkdown.keep()keep()Keep elements as HTML
toMarkdown.remove()remove()Remove elements
N/Ause()Apply plugins

​
3. Options Changes

Some option names have changed: 
var markdown = toMarkdown(html, {
  gfm: true,
  converters: [/* custom converters */]
})

​
4. GitHub Flavored Markdown (GFM)

GFM support is no longer built-in. It’s now available as a separate plugin: 
var markdown = toMarkdown(html, {
  gfm: true
})

​
5. Custom Rules API

The API for custom rules has been simplified: 
toMarkdown.addRule('strikethrough', {
  filter: ['del', 's'],
  replacement: function (content, node) {
    return '~~' + content + '~~'
  }
})

​
6. Filter Function Signature

Filter functions now receive the options object: 
filter: function (node) {
  return node.nodeName === 'A'
}

​
Complete Migration Example

Here’s a complete before/after example: 
var toMarkdown = require('to-markdown')

// Add custom rule
toMarkdown.addRule('highlight', {
  filter: 'mark',
  replacement: function (content) {
    return '==' + content + '=='
  }
})

// Convert with options
var markdown = toMarkdown('<p>Hello <mark>world</mark></p>', {
  gfm: true,
  headingStyle: 'atx'
})

console.log(markdown)

​
Official Migration Guide

For detailed migration information, including edge cases and advanced scenarios, refer to the official migration guide:

Official Migration Guide

Comprehensive guide on the GitHub wiki with detailed examples and troubleshooting

​
Common Migration Issues

​
Issue: “TurndownService is not a constructor”

Solution: Make sure you’re instantiating Turndown with new: 
// Wrong
var turndownService = TurndownService()

// Correct
var turndownService = new TurndownService()

​
Issue: GFM Features Not Working

Solution: Install and use the GFM plugin: 
npm install turndown-plugin-gfm

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

​
Issue: Custom Rules Not Applied

Solution: Ensure you’re calling addRule() on the service instance: 
// Wrong
TurndownService.addRule('myRule', {/* ... */})

// Correct
turndownService.addRule('myRule', {/* ... */})

​
Repository Changes

The Turndown repository has moved:
  • Old URL: https://github.com/domchristie/to-markdown
  • New URL: https://github.com/mixmark-io/turndown
Update any references in your documentation, CI/CD pipelines, or dependency management systems.

​
Backward Compatibility

Turndown does not provide backward compatibility with to-markdown. You must update your code to use the new API. However, the core functionality remains the same, and most migrations can be completed quickly.

​
Need Help?

If you encounter issues during migration:
  1. Check the GitHub Issues for similar problems
  2. Review the official migration guide
  3. Open a new issue with details about your migration challenge

​
Next Steps

Getting Started

Learn the basics of using Turndown

Custom Rules

Extend Turndown with custom conversion rules

GFM Plugin

Add GitHub Flavored Markdown support

API Reference

Explore the complete API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us