@aboveyou00/markdown-it 中文文档教程

Question

markdown-it

< /a>

Markdown 解析器做对了。 快速且易于扩展。

现场演示

• Follows the CommonMark spec + adds syntax extensions & sugar (URL autolinking, typographer).
• Configurable syntax! You can add new rules and even replace existing ones.
• High speed.
• Safe by default.
• Community-written plugins and other packages on npm.

目录

• Install
• Usage examples
• API
• Syntax extensions
• Benchmark
• Authors
• References / Thanks
• License

Install

node.js & bower：

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

浏览器 (CDN)：

• jsDeliver CDN
• cdnjs.com CDN

Usage examples

另请参阅：

• API documentation - for more info and examples.
• Development info - for plugins writers.

Simple

// node.js, "classic" way:
var MarkdownIt = require('markdown-it'),
    md = new MarkdownIt();
var result = md.render('# markdown-it rulezz!');

// node.js, the same, but with sugar:
var md = require('markdown-it')();
var result = md.render('# markdown-it rulezz!');

// browser without AMD, added to "window" on script load
// Note, there is no dash in "markdownit".
var md = window.markdownit();
var result = md.render('# markdown-it rulezz!');

单行呈现，无段落换行：

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

Init with presets and options

(*) 预设定义活动规则和选项的组合。 可 “commonmark”、“zero” 或 “default”（如果跳过）。 看 API 文档了解更多详情。

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

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

// enable everything
var md = require('markdown-it')({
  html: true,
  linkify: true,
  typographer: true
});

// full options list (defaults)
var md = require('markdown-it')({
  html:         false,        // Enable HTML tags in source
  xhtmlOut:     false,        // Use '/' to close single tags (<br />).
                              // This is only for full CommonMark compatibility.
  breaks:       false,        // Convert '\n' in paragraphs into <br>
  langPrefix:   'language-',  // CSS language prefix for fenced blocks. Can be
                              // useful for external highlighters.
  linkify:      false,        // Autoconvert URL-like text to links

  // Enable some language-neutral replacement + quotes beautification
  typographer:  false,

  // Double + single quotes replacement pairs, when typographer enabled,
  // and smartquotes on. Could be either a String or an Array.
  //
  // For example, you can use '«»„“' for Russian, '„“‚‘' for German,
  // and ['«\xA0', '\xA0»', '‹\xA0', '\xA0›'] for French (including nbsp).
  quotes: '“”‘’',

  // Highlighter function. Should return escaped HTML,
  // or '' if the source string is not changed and should be escaped externaly.
  // If result starts with <pre... internal wrapper is skipped.
  highlight: function (/*str, lang*/) { return ''; }
});

Plugins load

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

Syntax highlighting

使用 highlight 选项将语法突出显示应用于围栏代码块：

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

// Actual default values
var md = require('markdown-it')({
  highlight: function (str, lang) {
    if (lang && hljs.getLanguage(lang)) {
      try {
        return hljs.highlight(lang, str).value;
      } catch (__) {}
    }

    return ''; // use external default escaping
  }
});

或使用完整包装器覆盖（如果您需要将类分配给

）：

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

// Actual default values
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);  // disables .py as top level domain

API

API文档< /a>

如果你打算写插件 - 看看 开发信息。

Syntax extensions

嵌入式（默认启用）：

• Tables (GFM)
• Strikethrough (GFM)

通过插件：

• subscript
• superscript
• footnote
• definition list
• abbreviation
• emoji
• custom container
• insert
• mark
• … and others

Manage rules

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

// Activate/deactivate rules, with curring
var md = require('markdown-it')()
            .disable([ 'link', 'image' ])
            .enable([ 'link' ])
            .enable('image');

// Enable everything
md = require('markdown-it')({
  html: true,
  linkify: true,
  typographer: true,
});

Benchmark

以下是 MB Pro Retina 2013 (2.4 GHz) 的自述文件解析结果：

make benchmark-deps
benchmark/benchmark.js readme

Selected samples: (1 of 28)
 > README

Sample: README.md (7774 bytes)
 > commonmark-reference x 1,222 ops/sec ±0.96% (97 runs sampled)
 > current x 743 ops/sec ±0.84% (97 runs sampled)
 > current-commonmark x 1,568 ops/sec ±0.84% (98 runs sampled)
 > marked x 1,587 ops/sec ±4.31% (93 runs sampled)

注意。 CommonMark 版本使用 简化链接规范化器 进行更“诚实”的比较。 差异约为 1.5 倍。

如您所见，markdown-it 并没有因为它的灵活性而以速度为代价。 由于附加功能不可用而导致“完整”版本速度变慢 其他实现。

Authors

• Alex Kocharin github/rlidwka
• Vitaly Puzrin github/puzrin

markdown-it 是贡献给作者的决定的结果 将 99% 的 Remarkable 代码移至具有相同作者身份但 新的领导层（Vitaly 和 Alex）。 这不是叉子。

References / Thanks

非常感谢 John MacFarlane 在 CommonMark 规范和参考实现。 他的工作为我们节省了很多时间 在这个项目的开发过程中。

相关链接：

• https://github.com/jgm/CommonMark - reference CommonMark implementations in C & JS, also contains latest spec & online demo.
• http://talk.commonmark.org - CommonMark forum, good place to collaborate developers' efforts.

Ports

• motion-markdown-it - Ruby/RubyMotion

License

MIT