Skip to main content

​
Quickstart

This guide will walk you through your first HTML to Markdown conversion using Turndown. In just a few minutes, you’ll be converting HTML to clean, readable Markdown.

​
Before You Begin

Make sure you have Turndown installed. If not, follow the Installation guide first.

​
Your First Conversion

1

Import Turndown

First, import the TurndownService:
var TurndownService = require('turndown')
2

Create a service instance

Create a new instance of TurndownService:
var turndownService = new TurndownService()
You can call TurndownService with or without the new keyword - both work the same way.
3

Convert HTML to Markdown

Use the turndown() method to convert HTML:
var html = '<h1>Hello world!</h1>'
var markdown = turndownService.turndown(html)

console.log(markdown)
// Output: # Hello world!
Congratulations! You’ve just converted your first HTML to Markdown.

​
More Examples

​
Converting Complex HTML

Turndown handles complex HTML structures with ease: 
var TurndownService = require('turndown')
var turndownService = new TurndownService()

var html = `
  <article>
    <h1>Getting Started with Turndown</h1>
    <p>Turndown is a <strong>powerful</strong> HTML to Markdown converter.</p>
    <h2>Features</h2>
    <ul>
      <li>CommonMark support</li>
      <li>Highly configurable</li>
      <li>Plugin system</li>
    </ul>
    <blockquote>
      <p>It just works!</p>
    </blockquote>
  </article>
`

var markdown = turndownService.turndown(html)
console.log(markdown)
Output: 
Getting Started with Turndown
==============================

Turndown is a **powerful** HTML to Markdown converter.

Features
--------

*   CommonMark support
*   Highly configurable
*   Plugin system

> It just works!

​
Converting DOM Elements

In a browser environment, you can convert DOM elements directly: 
var turndownService = new TurndownService()

// Convert a specific element
var contentDiv = document.getElementById('content')
var markdown = turndownService.turndown(contentDiv)

// Convert the entire document
var fullMarkdown = turndownService.turndown(document)

// Convert a document fragment
var fragment = document.createDocumentFragment()
// ... add nodes to fragment
var fragmentMarkdown = turndownService.turndown(fragment)

​
Customizing the Conversion

​
Basic Configuration

Customize how Turndown converts HTML by passing options to the constructor: 
var turndownService = new TurndownService({
  headingStyle: 'atx',           // Use # for headings instead of underlines
  codeBlockStyle: 'fenced',      // Use ``` for code blocks
  bulletListMarker: '-',         // Use - for bullet lists
  emDelimiter: '*',              // Use * for emphasis
  strongDelimiter: '**'          // Use ** for strong
})

var html = '<h1>Title</h1><p><em>italic</em> and <strong>bold</strong></p>'
var markdown = turndownService.turndown(html)

console.log(markdown)
// Output:
// # Title
//
// *italic* and **bold**

​
Common Options

// Setext style (default): uses underlines for h1 and h2
var service1 = new TurndownService({ headingStyle: 'setext' })
service1.turndown('<h1>Title</h1>')
// Title
// =====

// ATX style: uses # for all headings
var service2 = new TurndownService({ headingStyle: 'atx' })
service2.turndown('<h1>Title</h1>')
// # Title
For a complete list of options, see Conversion Options.

​
Working with Code

​
Inline Code

var html = '<p>Use the <code>turndown()</code> method to convert HTML.</p>'
var markdown = turndownService.turndown(html)

console.log(markdown)
// Output: Use the `turndown()` method to convert HTML.

​
Code Blocks with Language

var html = `
  <pre><code class="language-javascript">
function hello() {
  console.log('Hello world!');
}
  </code></pre>
`

var turndownService = new TurndownService({ codeBlockStyle: 'fenced' })
var markdown = turndownService.turndown(html)

console.log(markdown)
Output: 
\`\`\`javascript
function hello() {
  console.log('Hello world!');
}
\`\`\`

​
Error Handling

Turndown throws a TypeError if you pass invalid input: 
var turndownService = new TurndownService()

try {
  var markdown = turndownService.turndown(null)
} catch (error) {
  console.error(error.message)
  // Output: null is not a string, or an element/document/fragment node.
}
Valid input types:
  • Strings containing HTML
  • Element nodes (nodeType === 1)
  • Document nodes (nodeType === 9)
  • Document fragment nodes (nodeType === 11)

​
Complete Example

Here’s a complete working example bringing it all together: 
var TurndownService = require('turndown')

// Create service with custom options
var turndownService = new TurndownService({
  headingStyle: 'atx',
  codeBlockStyle: 'fenced',
  bulletListMarker: '-'
})

// HTML content to convert
var html = `
  <article>
    <h1>My Blog Post</h1>
    <p>This is a paragraph with <strong>bold</strong> and <em>italic</em> text.</p>
    
    <h2>Code Example</h2>
    <pre><code class="language-javascript">
const greeting = 'Hello, world!';
console.log(greeting);
    </code></pre>
    
    <h2>Features</h2>
    <ul>
      <li>Easy to use</li>
      <li>Highly configurable</li>
      <li>Great output</li>
    </ul>
    
    <p>Read more at <a href="https://example.com">our website</a>.</p>
  </article>
`

// Convert to Markdown
var markdown = turndownService.turndown(html)

console.log(markdown)

​
Next Steps

Now that you’ve completed the quickstart, explore these topics to get the most out of Turndown:

Conversion Options

Learn about all available configuration options

Custom Rules

Create custom rules to handle specific HTML elements

Plugins

Extend Turndown with plugins like GFM support

API Reference

Explore the complete API documentation
Pro Tip: Start with the default options and customize as needed. Turndown’s defaults follow CommonMark conventions and work well for most use cases.

Build docs developers (and LLMs) love

Get started for freeTalk to us