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

Import Turndown

First, import the TurndownService:

Node.js
ES Module
Browser

var TurndownService = require('turndown')

import TurndownService from 'turndown'

<script src="https://unpkg.com/turndown/dist/turndown.js"></script>
<!-- TurndownService is now available globally -->

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.

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

Heading Styles
Code Block Styles
Link Styles

// 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

// Indented code blocks (default)
var service1 = new TurndownService({ codeBlockStyle: 'indented' })
service1.turndown('<pre><code>var x = 1;</code></pre>')
//     var x = 1;

// Fenced code blocks
var service2 = new TurndownService({ codeBlockStyle: 'fenced' })
service2.turndown('<pre><code>var x = 1;</code></pre>')
// ```
// var x = 1;
// ```

// Inlined links (default)
var service1 = new TurndownService({ linkStyle: 'inlined' })
service1.turndown('<a href="/page">Link</a>')
// [Link](/page)

// Referenced links
var service2 = new TurndownService({ linkStyle: 'referenced' })
service2.turndown('<a href="/page">Link</a>')
// [Link][1]
//
// [1]: /page

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.

Get Started

Core Concepts

Guides

Quickstart

Quickstart

Before You Begin

Your First Conversion

More Examples

Converting Complex HTML

Converting DOM Elements

Customizing the Conversion

Basic Configuration

Common Options

Working with Code

Inline Code

Code Blocks with Language

Error Handling

Complete Example

Next Steps

Conversion Options

Custom Rules

Plugins

API Reference

​Quickstart

​Before You Begin

​Your First Conversion

​More Examples

​Converting Complex HTML

​Converting DOM Elements

​Customizing the Conversion

​Basic Configuration

​Common Options

​Working with Code

​Inline Code

​Code Blocks with Language

​Error Handling

​Complete Example

​Next Steps

Conversion Options

Custom Rules

Plugins

API Reference

Quickstart

Before You Begin

Your First Conversion

More Examples

Converting Complex HTML

Converting DOM Elements

Customizing the Conversion

Basic Configuration

Common Options

Working with Code

Inline Code

Code Blocks with Language

Error Handling

Complete Example

Next Steps