Use markdown-it to render Markdown to HTML

Use markdown-it to render Markdown to HTML, configure plugins, custom rendering rules, syntax highlighting.

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

bash

npm install markdown-it

Basic Usage

js

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:

js

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

js

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:

js

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

Plugin	Feature
markdown-it-sub	Subscript ~subscript~
markdown-it-sup	Superscript ^superscript^
markdown-it-footnote	Footnotes [^1]
markdown-it-deflist	Definition lists
markdown-it-abbr	Abbreviations <abbr>
markdown-it-emoji	Emoji :smile:
markdown-it-container	Custom containers ::: warning
markdown-it-ins	Insert <ins> via ++text++
markdown-it-mark	Mark <mark> via ==text==
markdown-it-for-inline	Iterator for traversing inline tokens
markdown-it-anchor	Heading anchor IDs

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

Rule Management

js

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

Syntax Highlighting

With highlight.js:

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:

js

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:

js

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:

js

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

CLI

bash

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