Markdown-it 使用教程

安装

node.js & bower:

npm install markdown-it --save
bower install markdown-it --save

browser (CDN):

• jsDeliver CDN
• cdnjs.com CDN

用法示例

参考：

• 开发者信息 - 为插件开发者准备。

简单用法

node.js版

// node.js, 用“类”的方式：
var MarkdownIt = require('markdown-it');
var md = new MarkdownIt();
var result = md.render('# markdown-it rulezz!');

// node.js, 写法2：(其实是一样的，语法糖)
var md = require('markdown-it')();
var result = md.render('# markdown-it rulezz!');

js加载版 (非AMD浏览器环境)

// 其他环境。没有 AMD 的浏览器环境，在 js 脚本加载时才添加到“window”
var md = window.markdownit(); // 注意，“markdownit” 中没有破折号
var result = md.render('# markdown-it rulezz!');

Vue + Typescript版 (npm版)

先安装包：

# 在此之前先init好项目（若您已经准备好了则跳过）
npm init vue@latest
git init

# md-it相关包
npm install --save markdown-it
npm install --save-dev @types/markdown-it

代码：

<script lang="ts">
import MarkdownIt from 'markdown-it'
const mdParser = new MarkdownIt();
const htmlText = mdParser.render(mdText);
el.innerHTML = htmlText;
...

VuePress2 + Typescript版本 (通过定义回调函数)

详见VuePress的笔记

略，这里使用不算稳定的VuePress2，是因为我并不是在上面部署稳定服务。开发插件内容主要依赖Md-it而非VuePress专属插件，VuePress接口更替对我来说应该影响不大。

环境准备：

# init
git init
pnpm init

# vuepress和vue相关包
pnpm add -D vuepress@next @vuepress/client@next vue

# 不需要md-it相关包 (VuePress已经自带了)
# pnpm install --save markdown-it
# pnpm install --save-dev @types/markdown-it

准备package.json，往里面添加一些script：

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

准备其他文件，包括.gitignore和README.md

echo 'node_modules' >> .gitignore
echo '.temp' >> .gitignore
echo '.cache' >> .gitignore
mkdir docs
echo '# Hello VuePress' > docs/README.md

启动服务

$ pnpm docs:dev

插件的基本使用：在你的 .vuepress/config.js 文件中增加一个"markdown"字段，并使用插件：

module.exports = {
  markdown: {
    extendMarkdown: md => {
      md.use(require('markdown-it-checkbox'))
    },
  },
};

单行渲染版

单行渲染，不进行段落换行：

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

带有预设和选项的初始化

三种模式

预设 (preset) 定义了激活的规则以及选项的组合

markdown-it 提供了三种模式：

• commonmark
  • 对应：最严格 解析模式
• default (默认)
  • 对应：GFM 解析模式
• zero
  • 对应：最宽松 解析模式

// 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 md = require('markdown-it')({
  html:         false,        // 在源码中启用 HTML 标签
  xhtmlOut:     false,        // 使用 '/' 来闭合单标签 （比如 <br />）。
                              // 这个选项只对完全的 CommonMark 模式兼容。
  breaks:       false,        // 转换段落里的 '\n' 到 <br>。
  langPrefix:   'language-',  // 给围栏代码块的 CSS 语言前缀。对于额外的高亮代码非常有用。
  linkify:      false,        // 将类似 URL 的文本自动转换为链接。

  // 启用一些语言中立的替换 + 引号美化
  typographer:  false,

  // 双 + 单引号替换对，当 typographer 启用时。
  // 或者智能引号等，可以是 String 或 Array。
  //
  // 比方说，你可以支持 '«»„“' 给俄罗斯人使用， '„“‚‘'  给德国人使用。
  // 还有 ['«\xA0', '\xA0»', '‹\xA0', '\xA0›'] 给法国人使用（包括 nbsp）。
  quotes: '“”‘’',

  // 高亮函数，会返回转义的HTML。
  // 或 '' 如果源字符串未更改，则应在外部进行转义。
  // 如果结果以 <pre ... 开头，内部包装器则会跳过。
  highlight: function (/*str, lang*/) { return ''; }
});

插件加载

var md = require('markdown-it')()
            .use(plugin1)
            .use(plugin2, opts, ...)
            .use(plugin3);

语法高亮

使用 highlight 选项给围栏代码块应用语法高亮功能：

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).value;
      } catch (__) {}
    }

    return ''; // 使用额外的默认转义
  }
});

或者使用完全的包裹器覆盖（如果你需要复制 class 到 <pre>）：

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

// 通常的默认值们
var md = require('markdown-it')({
  highlight: function (str, lang) {
    if (lang && hljs.getLanguage(lang)) {
      try {
        return '<pre class="hljs"><code>' +
               hljs.highlight(lang, str, true).value +
               '</code></pre>';
      } catch (__) {}
    }

    return '<pre class="hljs"><code>' + md.utils.escapeHtml(str) + '</code></pre>';
  }
});

Linkify

linkify: true 使用 linkify-it。配置 linkify-it，通过 md.linkify 访问 linkify 实例：

md.linkify.tlds('.py', false);  // 禁用 .py 作为顶级域

语法拓展

内嵌的（默认启用）：

• 表格 (GFM)
• 删除线 (GFM)

通过插件：

• 下标
• 上标
• 脚注
• 定义列表
• 缩写
• emoji
• 自定义代码块
• 插入
• 标记
• ...以及其他的

管理规则

默认情况下，所有规则都已经启用，但可以通过选项进行限制。在插件上加载其所有规则都会自动启用。

// 当前激活/禁用的规则
var md = require('markdown-it')()
            .disable([ 'link', 'image' ])
            .enable([ 'link' ])
            .enable('image');

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