markdown-it/markdown-it
GitHub: markdown-it/markdown-it
markdown-it 是一个高性能、完全遵循 CommonMark 规范的 Markdown 解析器，支持通过插件和可配置规则扩展语法。
Stars: 21595 | Forks: 1834
# markdown-it
[](https://github.com/markdown-it/markdown-it/actions/workflows/ci.yml)
[](https://www.npmjs.org/package/markdown-it)
[](https://coveralls.io/github/markdown-it/markdown-it?branch=master)
__[在线演示](https://markdown-it.github.io)__
- 遵循 __[CommonMark 规范](http://spec.commonmark.org/)__ + 添加语法扩展和语法糖 (URL 自动链接、排版工具)。
- 语法可配置！你可以添加新规则，甚至替换现有规则。
- 高速。
- 默认[安全](https://github.com/markdown-it/markdown-it/tree/master/docs/safety.md)。
- npm 上由社区编写的 __[插件](https://www.npmjs.org/browse/keyword/markdown-it-plugin)__ 和[其他包](https://www.npmjs.org/browse/keyword/markdown-it)。
__目录__
- [安装](#install)
- [用法示例](#usage-examples)
- [简单示例](#simple)
- [使用预设和选项初始化](#init-with-presets-and-options)
- [加载插件](#plugins-load)
- [语法高亮](#syntax-highlighting)
- [Linkify](#linkify)
- [API](#api)
- [语法扩展](#syntax-extensions)
- [管理规则](#manage-rules)
- [基准测试](#benchmark)
- [作者](#authors)
- [参考 / 致谢](#references--thanks)
## 安装
**node.js**:
```
npm install markdown-it
```
## 用法示例
另请参见：
- __[API 文档](https://markdown-it.github.io/markdown-it/)__ - 了解更多
信息和示例。
- [开发信息](https://github.com/markdown-it/markdown-it/tree/master/docs) -
面向插件作者。
### 简单示例
```
// node.js
// can use `require('markdown-it')` for CJS
import markdownit from 'markdown-it'
const md = markdownit()
const result = md.render('# markdown-it rulezz!');
// browser with UMD build, added to "window" on script load
// Note, there is no dash in "markdownit".
const md = window.markdownit();
const result = md.render('# markdown-it rulezz!');
```
单行渲染，不带段落包裹：
```
import markdownit from 'markdown-it'
const md = markdownit()
const result = md.renderInline('__markdown-it__ rulezz!');
```
### 使用预设和选项初始化
(*) 预设定义了激活规则和选项的组合。可以是
`"commonmark"`、`"zero"` 或 `"default"`（如果省略）。有关更多详细信息，请参见
[API 文档](https://markdown-it.github.io/markdown-it/#MarkdownIt.new)。
```
import markdownit from 'markdown-it'
// commonmark mode
const md = markdownit('commonmark')
// default mode
const md = markdownit()
// enable everything
const md = markdownit({
html: true,
linkify: true,
typographer: true
})
// full options list (defaults)
const md = markdownit({
// Enable HTML tags in source
html: false,
// Use '/' to close single tags (
). // This is only for full CommonMark compatibility. xhtmlOut: false, // Convert '\n' in paragraphs into
breaks: false, // CSS language prefix for fenced blocks. Can be // useful for external highlighters. langPrefix: 'language-', // Autoconvert URL-like text to links linkify: false, // Enable some language-neutral replacement + quotes beautification // For the full list of replacements, see https://github.com/markdown-it/markdown-it/blob/master/lib/rules_core/replacements.mjs 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 externally. // If result starts with` 或 `
). // This is only for full CommonMark compatibility. xhtmlOut: false, // Convert '\n' in paragraphs into
breaks: false, // CSS language prefix for fenced blocks. Can be // useful for external highlighters. langPrefix: 'language-', // Autoconvert URL-like text to links linkify: false, // Enable some language-neutral replacement + quotes beautification // For the full list of replacements, see https://github.com/markdown-it/markdown-it/blob/master/lib/rules_core/replacements.mjs 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 externally. // If result starts with
` 分配 class）：
```
import markdownit from 'markdown-it'
import hljs from 'highlight.js' // https://highlightjs.org
// Actual default values
const md = markdownit({
highlight: function (str, lang) {
if (lang && hljs.getLanguage(lang)) {
try {
return '' +
hljs.highlight(str, { language: lang, ignoreIllegals: true }).value +
'
';
} catch (__) {}
}
return '' + md.utils.escapeHtml(str) + '
';
}
});
```
### Linkify
`linkify: true` 使用 [linkify-it](https://github.com/markdown-it/linkify-it)。要
配置 linkify-it，请通过 `md.linkify` 访问 linkify 实例：
```
md.linkify.set({ fuzzyEmail: false }); // disables converting email to link
```
## API
__[API 文档](https://markdown-it.github.io/markdown-it/)__
如果你打算编写插件，请查看
[开发信息](https://github.com/markdown-it/markdown-it/tree/master/docs)。
## 语法扩展
内嵌（默认启用）：
- [表格](https://help.github.com/articles/organizing-information-with-tables/) (GFM)
- [删除线](https://help.github.com/articles/basic-writing-and-formatting-syntax/#styling-text) (GFM)
通过插件：
- [下标](https://github.com/markdown-it/markdown-it-sub)
- [上标](https://github.com/markdown-it/markdown-it-sup)
- [脚注](https://github.com/markdown-it/markdown-it-footnote)
- [定义列表](https://github.com/markdown-it/markdown-it-deflist)
- [缩写](https://github.com/markdown-it/markdown-it-abbr)
- [表情符号](https://github.com/markdown-it/markdown-it-emoji)
- [自定义容器](https://github.com/markdown-it/markdown-it-container)
- [插入](https://github.com/markdown-it/markdown-it-ins)
- [标记](https://github.com/markdown-it/markdown-it-mark)
- ... 以及[其他](https://www.npmjs.org/browse/keyword/markdown-it-plugin)
### 管理规则
默认情况下，所有规则都是启用的，但可以通过选项进行限制。在加载插件时，
其所有规则都会自动启用。
```
import markdownit from 'markdown-it'
// Activate/deactivate rules, with currying
const md = markdownit()
.disable(['link', 'image'])
.enable(['link'])
.enable('image');
// Enable everything
const md = markdownit({
html: true,
linkify: true,
typographer: true,
});
```
你可以在源码中找到所有规则：
- [`parser_core.mjs`](lib/parser_core.mjs)
- [`parser_block.mjs`](lib/parser_block.mjs)
- [`parser_inline.mjs`](lib/parser_inline.mjs)
## 基准测试
以下是在 MB Pro Retina 2013 (2.4 GHz) 上解析 readme 的结果：
```
npm run benchmark-deps
benchmark/benchmark.mjs 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)
```
如你所见，`markdown-it` 并没有为了灵活性而在速度上妥协。
“完整”版本变慢的原因是它包含了其他实现中不可用的额外功能。
## 作者
- Alex Kocharin [github/rlidwka](https://github.com/rlidwka)
- Vitaly Puzrin [github/puzrin](https://github.com/puzrin)
_markdown-it_ 源于贡献了 99% _Remarkable_ 代码的作者们所做出的决定：他们决定转向一个拥有相同作者但采用新领导层（Vitaly 和 Alex）的项目。它不是一个分支。
## 参考 / 致谢
非常感谢 [John MacFarlane](https://github.com/jgm) 在
CommonMark 规范和参考实现方面所做的工作。在本项目的开发过程中，
他的工作为我们节省了大量的时间。
**相关链接：**
- https://github.com/jgm/CommonMark - C & JS 的 CommonMark 参考实现，
还包含最新规范和在线演示。
- http://talk.commonmark.org - CommonMark 论坛，是协调
开发者工作的好地方。
**移植版**
- [motion-markdown-it](https://github.com/digitalmoksha/motion-markdown-it) - Ruby/RubyMotion
- [markdown-it-py](https://github.com/ExecutableBookProject/markdown-it-py)- Python标签：GNU通用公共许可证, Markdown解析器, MITM代理, Node.js, SOC Prime, 开发工具, 数据可视化, 文本处理, 自定义脚本