markdown-it

专业实现的 Markdown 解析器。速度快且易于扩展

https://markdown-it.github.io

特性

  • 遵循 CommonMark 规范 + 支持语法扩展（URL自动链接、排版优化）
  • 可配置语法！可添加新规则甚至替换现有规则
  • 高性能
  • 默认安全
  • 社区编写的插件及 npm 上的其他包

目录

  1. 安装
  2. 使用示例
    • 基础用法
    • 预设与配置初始化
    • 插件加载
    • 语法高亮
    • 链接转换
  3. api
  4. 语法扩展
  5. 规则管理
  6. 性能测试
  7. 企业版
  8. 作者
  9. 参考资源

安装

Node.js

npm install markdown-it

浏览器（CDN）

  • https://cdn.jsdelivr.net/npm/markdown-it/dist/markdown-it.min.js
  • https://cdnjs.cloudflare.com/ajax/libs/markdown-it/13.0.1/markdown-it.min.js

使用示例

另见：
https://markdown-it.github.io/markdown-it/ - 更多信息和示例
https://github.com/markdown-it/markdown-it/tree/master/docs - 插件开发者指南

基础用法

// Node.js (ESM)
import markdownit from 'markdown-it';
const md = markdownit();
const result = md.render('# markdown-it 太棒了!');

// 浏览器 (UMD 构建)
// 注意：全局对象名称为 markdownit（无连字符）
const md = window.markdownit();
const result = md.render('# markdown-it 太棒了!');

单行渲染（不包裹段落标签）

import markdownit from 'markdown-it';
const md = markdownit();
const result = md.renderInline('__markdown-it__ 太棒了!');

预设与配置初始化

import markdownit from 'markdown-it';

// CommonMark 模式
const md = markdownit('commonmark');

// 默认模式
const md = markdownit();

// 启用所有功能
const md = markdownit({
  html: true,          // 允许源文件中的HTML标签
  linkify: true,       // 自动转换URL为链接
  typographer: true    // 启用排版增强
});

// 完整配置项（默认值）
const md = markdownit({
  html: false,         // 是否解析源文件中的HTML标签
  xhtmlOut: false,     // 使用'/'闭合单标签（如<br />）
  breaks: false,       // 将段落中的'\n'转换为<br>
  langPrefix: 'language-', // 代码块CSS类前缀
  linkify: false,      // 自动转换类URL文本为链接
  typographer: false,  // 启用排版优化和替换规则
  quotes: '“”‘’',     // 启用typographer时的引号替换规则
  // 语法高亮函数，返回转义后的HTML
  highlight: (str, lang) => '' 
});

插件加载

import markdownit from 'markdown-it';

const md = markdownit()
  .use(plugin1)         // 加载插件1
  .use(plugin2, opts)   // 带参数加载插件2
  .use(plugin3);         // 加载插件3

语法高亮

通过 highlight 选项实现围栏代码块的语法高亮：

import markdownit from 'markdown-it';
import hljs from 'highlight.js'; // 需提前安装

const md = markdownit({
  highlight: (str, lang) => {
    if (lang && hljs.getLanguage(lang)) {
      try {
        return hljs.highlight(str, { language: lang }).value;
      } catch (_) {}
    }
    return ''; // 使用默认转义
  }
});

自定义高亮包装

import markdownit from 'markdown-it';
import hljs from 'highlight.js';

const md = markdownit({
  highlight: (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>`;
  }
});

链接转换

linkify: true 使用 https://github.com/markdown-it/linkify-it 库，通过 md.linkify 可配置：

md.linkify.set({ fuzzyEmail: false }); // 禁用邮箱自动转换

API

https://markdown-it.github.io/markdown-it/

语法扩展

内置扩展（默认启用）

  • 表格（GFM）
  • 删除线（GFM）

通过插件启用

  • 下标
  • 上标
  • 脚注
  • 定义列表
  • 缩写
  • 表情符号
  • 自定义容器
  • 插入符
  • 标记符
  • 等数十种插件

规则管理

import markdownit from 'markdown-it';

// 禁用/启用规则（链式调用）
const md = markdownit()
  .disable(['link', 'image'])  // 禁用链接和图片规则
  .enable('link')              // 重新启用链接规则
  .enable('image');            // 启用图片规则

// 查看规则源码：
// - parser_core.mjs
// - parser_block.mjs
// - parser_inline.mjs

性能测试

2013款 MacBook Pro Retina (2.4 GHz) 解析 README 的结果：

npm run benchmark-deps
benchmark/benchmark.mjs readme

测试结果：

Sample: README.md (7774 bytes)
 > commonmark-reference x 1,222 ops/sec
 > current x 743 ops/sec
 > current-commonmark x 1,568 ops/sec
 > marked x 1,587 ops/sec

注：CommonMark 版本使用简化的链接规范化处理，差异约1.5倍

企业版

作为 https://tidelift.com/subscription/pkg/npm-markdown-it?utm_source=npm-markdown-it&utm_medium=referral&utm_campaign=enterprise 的一部分提供商业支持。

作者

  • Alex Kocharin (https://github.com/rlidwka)
  • Vitaly Puzrin (https://github.com/puzrin)

markdown-it 是 Remarkable 项目原作者的转型成果（非分叉），99% 的代码贡献者迁移至此项目。

参考资源

致谢

特别感谢 John MacFarlane 对 CommonMark 规范和参考实现的贡献。

相关链接

  • https://github.com/jgm/CommonMark - C & JS 参考实现
  • http://talk.commonmark.org

衍生版本

  • https://github.com/digitalmoksha/motion-markdown-it (Ruby/RubyMotion)
  • https://github.com/executablebooks/markdown-it-py (Python)

总结

markdown-it 核心优势：

  1. 标准兼容性：严格遵循 CommonMark 规范，支持主流语法扩展
  2. 灵活扩展：通过插件机制可自由增减语法规则，配置粒度细
  3. 高性能：在同等功能下保持优秀的解析速度（约 700+ ops/sec）
  4. 生态完善：提供企业级支持，拥有丰富的社区插件生态
  5. 安全可靠：默认关闭 HTML 解析，避免 XSS 攻击风险

该库特别适用于需要深度定制 Markdown 解析规则的高要求场景，如文档系统、静态站点生成器等，其模块化架构和清晰的规则管理接口为开发者提供了强大的扩展能力。

最后更新: