turndown

Turndown is a small, dependency-light JavaScript library that converts HTML into Markdown. It accepts either an HTML string or a DOM node and produces CommonMark-compatible output, running the same code in Node.js (via domino) and directly in the browser.

Its real strength is extensibility: a rule engine lets you add custom conversion rules, keep or remove specific elements, override Markdown escaping, and layer in plugins such as GitHub Flavored Markdown support. This makes it a common building block for content pipelines, rich-text-to-Markdown editors, scrapers, and note-taking tools.

What You Get

• A TurndownService class that converts HTML strings or DOM nodes to CommonMark-style Markdown
• Configurable options for heading style, bullet markers, code-block fencing, emphasis and link styles
• An extensible rule system (addRule, keep, remove) plus a plugin API (use) for behaviors like GFM tables and strikethrough
• Isomorphic builds (CJS, ESM, UMD, IIFE) that run in Node.js and the browser

Common Use Cases

• Converting WYSIWYG/rich-text editor HTML into Markdown for storage
• Turning scraped or fetched web pages into Markdown for LLM ingestion or archival
• Migrating CMS or blog content from HTML to Markdown files
• Building note-taking and clipping tools that save web content as Markdown

Under The Hood

Architecture

Turndown centers on the TurndownService constructor in src/turndown.js, which merges user options over CommonMark defaults and builds a Rules collection (src/rules.js). The turndown() entry point wraps input in a RootNode (src/root-node.js), then recursively reduces the DOM: process() walks childNodes, wrapping each in a Node (src/node.js) that computes block/blank/flanking-whitespace metadata, and replacementForNode() finds the first matching rule and applies its replacement function. A join() helper reconciles blank-line spacing between fragments, and postProcess() runs rule append hooks and trims the result. In Node.js the HTML is parsed via @mixmark-io/domino (src/html-parser.js); in the browser the native DOMParser is used instead.

Tech Stack

Pure JavaScript authored as ES modules with a single runtime dependency, @mixmark-io/domino (^2.2.0), for server-side DOM parsing. Rollup bundles four output formats (CJS, ESM, UMD, IIFE) plus browser-specific variants via config files under config/, with Babel transforms for block-scoping and shorthand properties. Standard (standardjs) enforces style. Engines require Node >=18. There is no TypeScript in the source, though the library is widely paired with community type definitions.

Code Quality

The codebase is compact and readable, with each concern isolated in its own small module (rules, node, root-node, collapse-whitespace, utilities). Public methods carry JSDoc, and there is a real test suite: test/turndown-test.js drives fixture-based conversions through turndown-attendant plus explicit edge cases (null/undefined input, malformed documents, rule precedence, chaining return values), and test/internals-test.js exercises internal helpers. Notable care shows in details like the hand-rolled trimTrailingNewlines to avoid a regex backtracking bottleneck (issue #370). Style is enforced by standard in the test script.

API Design

The developer experience is excellent for its scope: new TurndownService().turndown(html) is the entire happy path, and every extension point (addRule, keep, remove, use, escape override, and constructor options) returns the instance for chaining and is documented in the README with copy-paste examples. Option names read naturally (headingStyle, bulletListMarker, codeBlockStyle), and the rule filter/replacement contract is small and consistent, making custom rules and plugins straightforward to write.