Remark -岩石教程

特点

高度可扩展: 提供丰富的插件体系，可以轻松扩展和定制功能。
抽象语法树（AST）: 解析 Markdown 为 AST，便于进一步处理和转换。
多格式支持: 除了 HTML，还支持其他格式的输出和转换。
社区驱动: 活跃的社区和丰富的插件生态系统。
性能优良: 解析速度快，能够处理大规模的 Markdown 内容。

使用场景

博客和文章发布平台
文档和知识库系统
代码注释和文档生成
在线 Markdown 编辑器
自定义 Markdown 处理工具

安装方式

使用 npm 或 yarn 安装

npm install remark
# 或者
yarn add remark

使用示例

在 Node.js 环境中使用 Remark 将 Markdown 转换为 HTML

const remark = require('remark');
const html = require('remark-html');

remark()
  .use(html)
  .process('# Hello, Remark!', function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

在浏览器环境中使用

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Remark Example</title>
  <script src="https://cdn.jsdelivr.net/npm/remark/dist/remark.min.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/remark-html/dist/remark-html.min.js"></script>
</head>
<body>
  <h1>Remark Example</h1>
  <div id="content"></div>
  <script>
    remark()
      .use(remarkHtml)
      .process('# Hello, Remark!', function (err, file) {
        if (err) throw err;
        document.getElementById('content').innerHTML = String(file);
      });
  </script>
</body>
</html>

常用 API 介绍

1. remark()

描述: 创建并初始化 Remark 实例。

示例:

const processor = remark();

2. processor.use(plugin, options)

描述: 使用插件扩展 Remark 的功能。

参数:

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

示例:

const html = require('remark-html');
processor.use(html);

3. processor.process(markdownString, callback)

描述: 将 Markdown 字符串解析为指定格式（默认是 HTML），异步处理。

参数:

markdownString: 字符串，包含要解析的 Markdown 内容。
callback: 回调函数，处理完成后的回调。

示例:

processor.process('# Hello, Remark!', function (err, file) {
  if (err) throw err;
  console.log(String(file));
});

4. processor.processSync(markdownString)

描述: 将 Markdown 字符串解析为指定格式（默认是 HTML），同步处理。

参数:

markdownString: 字符串，包含要解析的 Markdown 内容。

示例:

const file = processor.processSync('# Hello, Remark!');
console.log(String(file));

5. processor.parse(markdownString)

描述: 将 Markdown 字符串解析为 AST（抽象语法树）。

参数:

markdownString: 字符串，包含要解析的 Markdown 内容。

示例:

const ast = processor.parse('# Hello, Remark!');
console.log(ast);

6. processor.stringify(ast)

描述: 将 AST（抽象语法树）转换为字符串（默认是 Markdown 格式）。

参数:

ast: 抽象语法树对象。

示例:

const ast = processor.parse('# Hello, Remark!');
const markdownString = processor.stringify(ast);
console.log(markdownString);

高级用法

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

示例:

function myPlugin() {
  return function transformer(tree) {
    visit(tree, 'text', function (node) {
      if (node.value === 'Remark') {
        node.value = 'Custom Remark';
      }
    });
  };
}

processor.use(myPlugin);

const file = processor.processSync('Hello, Remark!');
console.log(String(file)); // 输出 <p>Hello, Custom Remark!</p>

示例中的 visit 函数: visit 是 unist-util-visit 库中的函数，用于遍历 AST 节点。你需要安装 unist-util-visit 库：

npm install unist-util-visit

然后在代码中导入：

const visit = require('unist-util-visit');

Remark

特点

使用场景

安装方式

使用示例

常用 API 介绍

高级用法

官方资料