markdown-it MarkdownIt API 文档

本文介绍 markdown-it 的 MarkdownIt 类 API 文档，markdown-it 是一个快速、可扩展的 Markdown 解析器，广泛用于前端项目中将 Markdown 转换为 HTML。

说明

MarkdownIt 是 markdown-it 的主要解析器/渲染器类。

用法

Node.js 环境

使用"类"的方式：

var MarkdownIt = require('markdown-it'),
    md = new MarkdownIt();
var result = md.render('# markdown-it rulezz!');

更简洁的写法：

var md = require('markdown-it')();
var result = md.render('# markdown-it rulezz!');

浏览器环境

// 注意，"markdownit" 中没有破折号
var md = window.markdownit();
var result = md.render('# markdown-it rulezz!');

单行渲染

没有段落包裹的内联渲染：

var md = require('markdown-it')();
var result = md.renderInline('__markdown-it__ rulezz!');

构造器

new MarkdownIt([presetName][, options])

参数

presetName (String) - 可选，可选值：commonmark / zero
options (Object) - 配置选项

用给定的配置创建解析器实例。可以不调用 "new"。

预设配置名

MarkdownIt 提供命名的预设（配置），以便快速启用/禁用常用语法规则和选项：

commonmark - 将解析器配置为严格的 CommonMark 模式
default - 类似于 GFM，在没有给出预设名称时会启用，包含所有可用的规则，但仍然没有 html、typographer 和 autolinker
zero - 所有的规则都被禁用。通过 .enable() 快速设置你的配置是比较好的

选项

html - false。设成 true 来启用在源码中支持 HTML 标签。注意！这是不安全的！你可能需要额外的消毒剂来阻止来自 XSS 的输出。
xhtmlOut - false。设成 true 来给闭合的单个标签（<br />）添加 '/'。
breaks - false。设成 true 来转化段落里的 \n 成 <br>。
langPrefix - language-。给围栏代码块的 CSS 语言类前缀。
linkify - false。设成 true 来自动转化像 URL 的文本成链接。
typographer - false。设成 true 来启用某些语言中性的替换以及引号的美化（智能引号）。
quotes - ""''。String 或 Array 类型。在 typographer 启用和支持智能引号时，进行双引号 + 单引号对替换。
highlight - null。高亮函数，给围栏代码块使用的。高亮器 function (str, lang) 会返回转义后的 HTML。

示例

// commonmark 模式
var md = require('markdown-it')('commonmark');

// default 模式
var md = require('markdown-it')();

// 启用所有
var md = require('markdown-it')({
  html: true,
  linkify: true,
  typographer: true
});

语法高亮示例

var hljs = require('highlight.js'); // https://highlightjs.org/

var md = require('markdown-it')({
  highlight: function (str, lang) {
    if (lang && hljs.getLanguage(lang)) {
      try {
        return hljs.highlight(lang, str, true).value;
      } catch (__) {}
    }
    return ''; // 使用额外的默认转义
  }
});

类方法

MarkdownIt.configure

链式的内部方法，用于批量加载所有选项和编译设置。

MarkdownIt.configure(presets)

MarkdownIt.disable

链式方法，用于禁用指定的规则。

MarkdownIt.disable(list, ignoreInvalid)

list (String|Array) - 要禁用的规则名称或规则名称列表
ignoreInvalid (Boolean) - 设为 true 来忽略规则未发现时的错误

MarkdownIt.enable

链式方法，用于启用指定的规则。

MarkdownIt.enable(list, ignoreInvalid)

list (String|Array) - 要启用的规则名称或规则名称列表
ignoreInvalid (Boolean) - 设为 true 来忽略规则未发现时的错误

示例：

var md = require('markdown-it')()
            .enable(['sub', 'sup'])
            .disable('smartquotes');

MarkdownIt.parse

内部方法，解析输入字符串并返回块类型的 token 列表。

MarkdownIt.parse(src, env) -> Array

src (String|Array) - 源代码的字符串
env (Object) - 环境沙箱

MarkdownIt.parseInline

类似于 MarkdownIt.parse 但是会忽略所有块规则。

MarkdownIt.parseInline(src, env) -> Array

MarkdownIt.render

将 markdown 字符串转换为 HTML，这是最常用的方法。

MarkdownIt.render(src[, env]) -> String

src (String|Array) - 源代码的字符串
env (Object) - 环境沙箱，可用于注入附加的元数据（默认情况下为 {}）

MarkdownIt.renderInline

类似于 MarkdownIt.render，但对于单个段落的内容，结果不会被 <p> 标签包裹。

MarkdownIt.set

链式方法，设置解析器选项。

var md = require('markdown-it')()
            .set({ html: true, breaks: true })
            .set({ typographer: true });

注意： 为了获得最好的性能，不要频繁地修改一个 markdown-it 实例选项。如果需要多个配置，最好创建多个实例。

MarkdownIt.use

链式方法，将指定的插件加载到当前的解析器实例中。

var iterator = require('markdown-it-for-inline');
var md = require('markdown-it')()
            .use(iterator, 'foo_replace', 'text', function (tokens, idx) {
              tokens[idx].content = tokens[idx].content.replace(/foo/g, 'bar');
            });

实例方法

MarkdownIt#normalizeLink

用于将链接 URL 编码为机器可读格式的函数，包括 url 编码、punycode 等。

MarkdownIt#normalizeLink(url) -> String

MarkdownIt#normalizeLinkText

用于将链接 URL 解码为人类可读格式的函数。

MarkdownIt#normalizeLinkText(url) -> String

MarkdownIt#validateLink

链接校验函数。

MarkdownIt#validateLink(url) -> Boolean

默认情况下禁用 javascript:、vbscript:、file: schemas，以及几乎所有的 data:... schemas。

实例属性

MarkdownIt#block

ParserBlock 的实例。当编写插件时，你可能用它来添加新规则。

MarkdownIt#core

Core 的链式调用实例。

MarkdownIt#helpers

链接组件解析函数，对编写插件大有裨益。

MarkdownIt#inline

ParserInline 的实例。当编写插件时，你可能用它来添加新规则。

MarkdownIt#linkify

linkify-it 的实例，用于 linkify 规则。

MarkdownIt#renderer

Renderer 的实例。使用它来修改输出的外观，或者为插件生成的新 token 类型添加渲染规则。

MarkdownIt#utils

各种实用的函数，用于编写插件。

字节笔记本