markdown-it

markdown-it is a Markdown parser for Node.js/browser, 100% CommonMark compliant, supports plugin extensions and custom syntax. Current version 14.x, ESM/CJS dual mode.

Trigger Scenarios

Use when the user needs to parse/render Markdown, perform markdown-it related operations, or parse CommonMark.

Installation

npm install markdown-it

Basic Usage

import MarkdownIt from 'markdown-it';
const md = new MarkdownIt();
const html = md.render('# Hello markdown-it!');
// <h1>Hello markdown-it!</h1>

// Inline rendering (no paragraph wrapping)
md.renderInline('**bold** text');
// <strong>bold</strong> text

Presets

Three modes that control default enabled rules and options:

// CommonMark strict mode (standard syntax only)
const md = new MarkdownIt('commonmark');

// Default mode (CommonMark + tables + strikethrough, recommended)
const md = new MarkdownIt('default');
// Equivalent to
const md = new MarkdownIt();

// Zero rules mode (completely empty, configure everything yourself)
const md = new MarkdownIt('zero');

Complete Configuration Options

All defaults:

const md = new MarkdownIt({
  html:         false,  // Allow HTML tags in source text
  xhtmlOut:     false,  // Use '/' to close single tags (<br />)
  breaks:       false,  // Convert newlines to <br>
  langPrefix:   'language-', // CSS language prefix for fenced code blocks
  linkify:      false,  // Automatically convert URLs to links
  typographer:  false,  // Smart quotes + language replacements
  quotes:       '""',   // Double + single quote replacement pairs
  highlight: function (str, lang) { return ''; }
});

Plugin System

Chain .use() calls:

import MarkdownIt from 'markdown-it';
import markdownItSub from 'markdown-it-sub';
import markdownItSup from 'markdown-it-sup';

const md = new MarkdownIt()
  .use(markdownItSub)
  .use(markdownItSup, /* plugin options */);

Common Official Plugins

Built-in extensions (enabled by default): tables (GFM), strikethrough (GFM ~~text~~)

Rule Management

const md = new MarkdownIt();
md.disable(['link', 'image'])  // Disable specific rules
  .enable(['link'])            // Re-enable
  .enable('image');

Syntax Highlighting

With highlight.js:

import hljs from 'highlight.js';

const md = new MarkdownIt({
  highlight: function (str, lang) {
    if (lang && hljs.getLanguage(lang)) {
      try {
        return '<pre><code class="hljs">' +
               hljs.highlight(str, { language: lang, ignoreIllegals: true }).value +
               '</code></pre>';
      } catch (_) {}
    }
    return '<pre><code class="hljs">' + md.utils.escapeHtml(str) + '</code></pre>';
  }
});

Custom Rendering

Override renderer rules to modify output. For example, adding target="_blank" to all links:

const defaultRender = md.renderer.rules.link_open ||
  function(tokens, idx, options, env, self) {
    return self.renderToken(tokens, idx, options);
  };

md.renderer.rules.link_open = function (tokens, idx, options, env, self) {
  tokens[idx].attrSet('target', '_blank');
  return defaultRender(tokens, idx, options, env, self);
};

Converting Vimeo links to iframe embeds:

const defaultRender = md.renderer.rules.image;

md.renderer.rules.image = function (tokens, idx, options, env, self) {
  const src = tokens[idx].attrGet('src');
  if (/^https?:\/\/(www\.)?vimeo.com\//.test(src)) {
    const id = src.split('/').pop();
    return `<div class="embed-responsive"><iframe src="//player.vimeo.com/video/${id}"></iframe></div>`;
  }
  return defaultRender(tokens, idx, options, env, self);
};

linkify Configuration

After enabling linkify: true, you can further configure linkify-it:

md.linkify.set({ fuzzyEmail: false }); // Disable auto email linking
md.linkify.tlds('.py', false);         // Allow .py top-level domain

CLI

npm install -g markdown-it
markdown-it README.md > README.html

Security

• Does not parse HTML in source text by default (html: false) to prevent XSS
• Output is always HTML-escaped (unless using html: true)
• To render user-generated Markdown, keep html: false (default)

Reference Documentation

• Architecture principles and plugin development → Read references/architecture.md
• Plugin development FAQ → Read references/plugin-dev.md