CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-turndown

A library that converts HTML to Markdown

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

Turndown

Turndown is a JavaScript library that converts HTML to Markdown. It provides a configurable service with extensive customization options for heading styles, list markers, code block formatting, link styles, and text emphasis delimiters. The library features a rule-based conversion system and plugin architecture for extending functionality.

Package Information

  • Package Name: turndown
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install turndown

Core Imports

// CommonJS (Node.js) - Primary import method
const TurndownService = require('turndown');

// ES Modules (if using bundler that supports it)
import TurndownService from 'turndown';

Browser usage:

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

UMD usage:

// RequireJS
define(['turndown'], function(TurndownService) {
  // Use TurndownService
});

Basic Usage

const TurndownService = require('turndown');

const turndownService = new TurndownService();
const markdown = turndownService.turndown('<h1>Hello world!</h1>');
console.log(markdown); // "Hello world\n==========="

// With options
const turndownService = new TurndownService({
  headingStyle: 'atx',
  codeBlockStyle: 'fenced'
});

const html = '<h2>Example</h2><p>Convert <strong>HTML</strong> to <em>Markdown</em></p>';
const markdown = turndownService.turndown(html);

Architecture

Turndown is built around several key components:

  • TurndownService: Main class providing the conversion API and configuration management
  • Rule System: Flexible rule-based conversion engine that determines how each HTML element is converted
  • Plugin System: Extensible architecture allowing custom functionality through plugins
  • Options System: Comprehensive configuration for customizing output format and style
  • Cross-platform Parsing: HTML parsing that works in both browser and Node.js environments

Capabilities

TurndownService Constructor

Creates a new TurndownService instance with optional configuration.

/**
 * TurndownService constructor
 * @param {TurndownOptions} options - Optional configuration object
 * @returns {TurndownService} New TurndownService instance
 */
function TurndownService(options)

// Can also be called without 'new'
const turndownService = TurndownService(options);

HTML Conversion

Core HTML to Markdown conversion functionality with support for all standard HTML elements and DOM nodes.

/**
 * Convert HTML string or DOM node to Markdown
 * @param {string|HTMLElement|Document|DocumentFragment} input - HTML to convert
 * @returns {string} Markdown representation of the input
 */
turndown(input)

Configuration Options

Comprehensive configuration system for customizing Markdown output format and style.

/**
 * TurndownService constructor options
 */
interface TurndownOptions {
  headingStyle?: 'setext' | 'atx';           // Default: 'setext'
  hr?: string;                               // Default: '* * *'
  bulletListMarker?: '*' | '-' | '+';        // Default: '*'
  codeBlockStyle?: 'indented' | 'fenced';    // Default: 'indented'
  fence?: string;                            // Default: '```'
  emDelimiter?: '_' | '*';                   // Default: '_'
  strongDelimiter?: '**' | '__';             // Default: '**'
  linkStyle?: 'inlined' | 'referenced';     // Default: 'inlined'
  linkReferenceStyle?: 'full' | 'collapsed' | 'shortcut'; // Default: 'full'
  br?: string;                               // Default: '  '
  preformattedCode?: boolean;                // Default: false
  blankReplacement?: ReplacementFunction;    // Custom replacement for blank elements
  keepReplacement?: ReplacementFunction;     // Custom replacement for kept elements
  defaultReplacement?: ReplacementFunction; // Custom replacement for unrecognized elements
}

/**
 * Replacement function signature for custom rules
 */
type ReplacementFunction = (content: string, node: HTMLElement, options: TurndownOptions) => string;

Plugin System

Add custom functionality and extend conversion capabilities through plugins.

/**
 * Add one or more plugins to extend functionality
 * @param {Function|Function[]} plugin - Plugin function or array of plugin functions
 * @returns {TurndownService} TurndownService instance for chaining
 */
use(plugin)

Element Control

Control which HTML elements are kept as HTML, removed entirely, or converted with custom rules.

/**
 * Keep specified elements as HTML in the output
 * @param {string|string[]|Function} filter - Filter to match elements
 * @returns {TurndownService} TurndownService instance for chaining
 */
keep(filter)

/**
 * Remove specified elements entirely from output
 * @param {string|string[]|Function} filter - Filter to match elements
 * @returns {TurndownService} TurndownService instance for chaining
 */
remove(filter)

Rule System

Extensible rule-based conversion system for customizing how HTML elements are converted to Markdown.

/**
 * Add a custom conversion rule
 * @param {string} key - Unique identifier for the rule
 * @param {Object} rule - Rule object with filter and replacement properties
 * @returns {TurndownService} TurndownService instance for chaining
 */
addRule(key, rule)

/**
 * Rule object structure
 */
interface Rule {
  filter: string | string[] | Function;     // Selector for HTML elements
  replacement: Function;                    // Function to convert element to Markdown
}

Rule System

Markdown Escaping

Utility for escaping Markdown special characters to prevent unwanted formatting.

/**
 * Escape Markdown special characters with backslashes
 * @param {string} string - String to escape
 * @returns {string} String with Markdown syntax escaped
 */
escape(string)

TurndownService Class Interface

Complete interface definition for the TurndownService class.

/**
 * TurndownService class definition
 */
interface TurndownService {
  /** Service configuration options */
  options: TurndownOptions;
  
  /** Rules collection instance */
  rules: Rules;
  
  /** Convert HTML to Markdown */
  turndown(input: string | HTMLElement | Document | DocumentFragment): string;
  
  /** Add one or more plugins */
  use(plugin: Function | Function[]): TurndownService;
  
  /** Add a custom conversion rule */
  addRule(key: string, rule: Rule): TurndownService;
  
  /** Keep elements as HTML */
  keep(filter: string | string[] | Function): TurndownService;
  
  /** Remove elements entirely */
  remove(filter: string | string[] | Function): TurndownService;
  
  /** Escape Markdown special characters */
  escape(string: string): string;
}

/**
 * Internal Rules class (used internally by TurndownService)
 */
interface Rules {
  options: TurndownOptions;
  array: Rule[];
  blankRule: Rule;
  keepReplacement: ReplacementFunction;
  defaultRule: Rule;
  
  add(key: string, rule: Rule): void;
  keep(filter: string | string[] | Function): void;
  remove(filter: string | string[] | Function): void;
  forNode(node: HTMLElement): Rule;
  forEach(fn: (rule: Rule, index: number) => void): void;
}

Usage Examples

Basic HTML Conversion

const turndownService = new TurndownService();

// Convert HTML string
const markdown = turndownService.turndown('<p>Hello <strong>world</strong>!</p>');
// Result: "Hello **world**!"

// Convert DOM node
const element = document.getElementById('content');
const markdown = turndownService.turndown(element);

Custom Configuration

const turndownService = new TurndownService({
  headingStyle: 'atx',
  hr: '---',
  bulletListMarker: '-',
  codeBlockStyle: 'fenced',
  fence: '~~~',
  emDelimiter: '*',
  strongDelimiter: '__',
  linkStyle: 'referenced'
});

const html = `
  <h1>Title</h1>
  <ul>
    <li>Item 1</li>
    <li>Item 2</li>
  </ul>
  <pre><code>console.log('hello');</code></pre>
`;

const markdown = turndownService.turndown(html);

Element Control

const turndownService = new TurndownService();

// Keep certain elements as HTML
turndownService.keep(['del', 'ins']);
const result1 = turndownService.turndown('<p>Hello <del>world</del><ins>World</ins></p>');
// Result: "Hello <del>world</del><ins>World</ins>"

// Remove elements entirely
turndownService.remove('script');
const result2 = turndownService.turndown('<p>Content</p><script>alert("hi")</script>');
// Result: "Content"

Plugin Usage

// Define a plugin
function customPlugin(turndownService) {
  turndownService.addRule('strikethrough', {
    filter: ['del', 's', 'strike'],
    replacement: function(content) {
      return '~~' + content + '~~';
    }
  });
}

// Use the plugin
const turndownService = new TurndownService();
turndownService.use(customPlugin);

const result = turndownService.turndown('<p>This is <del>deleted</del> text</p>');
// Result: "This is ~~deleted~~ text"

Error Handling

Turndown throws specific errors for invalid inputs:

  • TypeError: When input to turndown() is not a string or valid DOM node
  • TypeError: When plugin passed to use() is not a function or array of functions
  • TypeError: When rule filter is not a string, array, or function
/**
 * Error types thrown by Turndown
 */
interface TurndownErrors {
  /** Thrown when turndown() receives invalid input */
  InvalidInputError: TypeError;  // "{input} is not a string, or an element/document/fragment node."
  
  /** Thrown when use() receives invalid plugin */
  InvalidPluginError: TypeError; // "plugin must be a Function or an Array of Functions"
  
  /** Thrown when rule filter is invalid */
  InvalidFilterError: TypeError; // "`filter` needs to be a string, array, or function"
}

Usage Examples:

const turndownService = new TurndownService();

// Invalid input to turndown()
try {
  turndownService.turndown(null);
} catch (error) {
  console.error(error.message); // "null is not a string, or an element/document/fragment node."
}

// Invalid plugin
try {
  turndownService.use("invalid");
} catch (error) {
  console.error(error.message); // "plugin must be a Function or an Array of Functions"
}

// Invalid rule filter
try {
  turndownService.addRule('test', { filter: 123, replacement: () => '' });
} catch (error) {
  console.error(error.message); // "`filter` needs to be a string, array, or function"
}

Browser and Node.js Support

Turndown works in both browser and Node.js environments:

  • Browser: Uses native DOMParser or fallback implementations (ActiveX for older IE)
  • Node.js: Uses domino library for DOM parsing
  • Build Targets: Available as CommonJS, ES modules, UMD, and IIFE formats

docs

index.md

rules.md

tile.json