Turndown
A JavaScript library that converts HTML into Markdown, in Node.js or the browser.
- Stars
- 11.5k
- Forks
- 999
- Licence
- MIT
- Language
- HTML
- Last update
- 19 days ago
- Type
- Library
What it is
Turndown is a JavaScript library that takes HTML and outputs Markdown text. You can call it from Node.js code or run it in a web page. It lets you customize how specific HTML elements are converted by adding rules, keeping or removing elements, or using plugins.
- Convert an HTML snippet to Markdown in a Node.js script with a few lines of code
- Convert the contents of a DOM element in the browser to Markdown
- Customize output, for example switching headings to ATX style or changing the bullet marker, using options
- Add a rule to change how a specific tag such as <del> is rendered, using addRule
- Keep or remove particular HTML elements during conversion using keep and remove
Great for
- Developers who need to convert HTML content, such as web pages or rich text editor output, into Markdown
- Node.js or browser projects that want a JavaScript-only conversion step
- Projects that need custom conversion rules for particular HTML tags
- Teams that want GitHub-flavored Markdown tables or strikethrough via the turndown-plugin-gfm plugin
Not ideal for
- Non-programmers who want a point-and-click converter, since the README only documents code usage
- Anyone who needs to convert Markdown back into HTML, since the README covers only HTML-to-Markdown conversion
- Projects needing exact round-trip fidelity, because the README notes its escaping rules can be quite aggressive
How to get it
- 1
Install with a package manager
You'll need: Node.js (version not specified in the README)
Install from npm
npm install turndown - 2
Run it
- Install the package with npm install turndown
- In Node.js, require TurndownService from 'turndown' and create an instance with new TurndownService()
- Call turndownService.turndown('<h1>Hello world!</h1>') to get the Markdown output
- 3
Get the most out of it
- Use the options table to set headingStyle, bulletListMarker, codeBlockStyle, or linkStyle to match your target Markdown style
- Install turndown-plugin-gfm and use it with turndownService.use(gfm) to add GFM tables and strikethrough
- Use addRule to customize how specific tags are converted
- Use keep and remove to control which HTML elements are preserved or dropped
Downloads
Strengths
- Simple API: create a service and call turndown() on HTML input, as shown in the README
- Configurable through documented options and extendable with custom rules and plugins
- Works in both Node.js and the browser, with UMD builds available for RequireJS
Trade-offs
- Escaping is handled with regular expressions and the README says the rules can be quite aggressive, which may alter text
- The README documents only the JavaScript API, so non-developers will need programming skills to use it
- Some features such as GFM tables depend on a separate plugin package
How it compares
| Project | Stars | Type | Level | Updated | Best for |
|---|---|---|---|---|---|
| turndown (this) | 11.5k | Library | beginner | 19 days ago | Developers who need to convert HTML content, such as web pages or rich text editor output, into Markdown |
| tui.editor | 18k | Library | intermediate | 2.3 years ago | Web developers who want an embeddable Markdown editor in their own site or app |
| react-markdown | 15.9k | Library | beginner | 1 months ago | React developers who need to display Markdown content such as comments, docs, or posts |
| showdown | 14.9k | Library | beginner | 8 days ago | JavaScript developers adding Markdown rendering to a web page |
| vditor | 11.4k | Library | intermediate | 19 days ago | Developers who want to embed a Markdown editor in a web app |
| mocha | 22.9k | Library | intermediate | 5 days ago | JavaScript and Node.js developers who want automated tests for their code |
Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.