markdown-it -岩石教程

特点

高性能: 使用精心设计的解析器，解析速度非常快。
高度可扩展: 提供插件机制，可以轻松扩展功能和自定义解析规则。
兼容性: 完全支持 CommonMark 规范，并提供了 GitHub Flavored Markdown (GFM) 的扩展。
安全性: 支持安全模式，防止 XSS 攻击。
支持 HTML 标签: 默认支持嵌入 HTML 标签，并可以根据需要配置。
开源: 源代码公开，活跃的社区支持和维护。

使用场景

博客和文章发布平台
文档和知识库系统
论坛和社区网站
在线 Markdown 编辑器
静态网站生成器

安装方式

使用 npm 或 yarn 安装

npm install markdown-it
# 或者
yarn add markdown-it

使用示例

在 Node.js 环境中使用 markdown-it 将 Markdown 转换为 HTML

const MarkdownIt = require('markdown-it');
const md = new MarkdownIt();

const markdownString = '# Hello, markdown-it!';
const htmlString = md.render(markdownString);

console.log(htmlString);

在浏览器环境中使用

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>markdown-it Example</title>
  <script src="https://cdn.jsdelivr.net/npm/markdown-it/dist/markdown-it.min.js"></script>
</head>
<body>
  <h1>markdown-it Example</h1>
  <div id="content"></div>
  <script>
    const md = window.markdownit();
    const markdownString = '# Hello, markdown-it!';
    const htmlString = md.render(markdownString);
    document.getElementById('content').innerHTML = htmlString;
  </script>
</body>
</html>

常用 API 介绍

1. new MarkdownIt(options)

描述: 创建并初始化 markdown-it 实例。

参数:

options: 可选参数，对象，包含配置选项。

示例:

const md = new MarkdownIt({
  html: true,
  linkify: true,
  typographer: true,
});

2. md.render(markdownString, env)

描述: 将 Markdown 字符串解析为 HTML 字符串。

参数:

markdownString: 字符串，包含要解析的 Markdown 内容。
env: 可选参数，对象，包含解析环境上下文。

示例:

const markdownString = '# Hello, markdown-it!';
const htmlString = md.render(markdownString);
console.log(htmlString);

3. md.renderInline(markdownString, env)

描述: 将 Markdown 字符串解析为 HTML 字符串，仅处理内联模式。

参数:

markdownString: 字符串，包含要解析的 Markdown 内容。
env: 可选参数，对象，包含解析环境上下文。

示例:

const markdownString = '**bold** and *italic*';
const htmlString = md.renderInline(markdownString);
console.log(htmlString);

4. md.set(options)

描述: 设置或更新解析器选项。

参数:

options: 对象，包含新的配置选项。

示例:

md.set({
  html: false,
});

5. md.use(plugin, options)

描述: 使用插件扩展 markdown-it 的功能。

参数:

plugin: 函数，插件定义。
options: 可选参数，对象，插件配置选项。

示例:

const emoji = require('markdown-it-emoji');
md.use(emoji);
const markdownString = 'Hello :smile:';
const htmlString = md.render(markdownString);
console.log(htmlString);

6. md.parse(markdownString, env)

描述: 将 Markdown 字符串解析为 Token 数组。

参数:

markdownString: 字符串，包含要解析的 Markdown 内容。
env: 可选参数，对象，包含解析环境上下文。

示例:

const markdownString = '# Hello, markdown-it!';
const tokens = md.parse(markdownString);
console.log(tokens);

7. md.renderer.rules

描述: 自定义渲染规则，通过修改 rules 对象来覆盖默认渲染规则。

示例:

md.renderer.rules.strong_open = function () {
  return '<b>';
};
md.renderer.rules.strong_close = function () {
  return '</b>';
};

const markdownString = '**bold text**';
const htmlString = md.render(markdownString);
console.log(htmlString); // 输出 <b>bold text</b>

高级用法

自定义插件: markdown-it 允许开发者创建自定义插件，以扩展或修改解析器的功能。例如，可以添加新的 Markdown 语法或修改默认的解析行为。

示例:

function myPlugin(md) {
  md.core.ruler.push('my_rule', function (state) {
    state.tokens.forEach(function (token) {
      if (token.type === 'inline' && token.content === 'foo') {
        token.content = 'bar';
      }
    });
  });
}

const md = new MarkdownIt();
md.use(myPlugin);

const markdownString = 'foo';
const htmlString = md.render(markdownString);
console.log(htmlString); // 输出 <p>bar</p>

markdown-it

特点

使用场景

安装方式

使用示例

常用 API 介绍

高级用法

官方资料