npm 包 remark-preset-github 使用教程

简介

在使用 Markdown 编写文档时，我们常常需要将其转换成 HTML 才能进行展示或者发布。而 remark 是一个流行的 Markdown 转换工具，它可以帮助我们将 Markdown 转换成各种格式，包括但不限于 HTML、LaTeX 和 PDF。

为了方便使用，remark 提供了预设 preset 来满足不同场景的需求，其中 remark-preset-github 是一个 GitHub 风格的预设，它基于 GitHub 的 Markdown 渲染样式，可以让 Markdown 文档更加接近 GitHub 上的渲染效果。

本文将介绍如何使用 npm 包 remark-preset-github 以及其相关插件，来优化 Markdown 转换体验。

安装

在使用 remark-preset-github 之前，我们需要先安装 remark：

npm install remark

然后再安装 remark-preset-github:

npm install remark-preset-github

配置

在安装完 remark 和 remark-preset-github 后，我们需要在代码中引入并配置这个预设，使其生效。下面是一个简单的示例：

-- -------------------- ---- -------
----- ------ - ------------------
----- ------ - --------------------------------

--------
  ------------
  ------- ----- ------- ---
  ---------------- -------- ----- ----- -- -
    --------------------------
  ---

这里我们通过 require 引入了 remark 和 remark-preset-github，然后创建了一个 remark 实例，并在其中使用了 github 这个预设。最后调用 process 方法将 Markdown 文本转换成 HTML。

配置选项

remark-preset-github 提供了一些可选的配置选项，可以让我们进一步定制化 Markdown 转换效果。下面是一些常用的配置选项：

commonmark

commonmark 是一个布尔值，表示是否启用 CommonMark 规范的 Markdown 语法，默认为 false。

remark()
  .use(github, { commonmark: true })
  .use(/* other plugins */);

gfm

gfm 是一个布尔值，表示是否启用 GitHub Flavored Markdown 的语法扩展，默认为 true。

remark()
  .use(github, { gfm: false })
  .use(/* other plugins */);

tableOfContents

tableOfContents 是一个对象，表示是否启用目录生成功能。该对象包含两个配置项：heading 和 maxDepth。

remark()
  .use(github, {
    tableOfContents: {
      heading: 'Table of Contents',
      maxDepth: 3,
    },
  })
  .use(/* other plugins */);

这里我们设置了目录的标题为 "Table of Contents"，最大深度为 3 层。

插件

除了预设 preset 外，remark 还提供了大量的插件，可以进一步扩展 Markdown 的转换功能。下面介绍一些常用的插件：

remark-math

remark-math 是一个让 remark 支持 LaTeX 公式的插件。使用该插件需要先安装 KaTeX。

npm install remark-math katex

然后在代码中引入并配置该插件：

-- -------------------- ---- -------
----- ---- - -----------------------
----- ----- - -----------------

--------
  ------------
  ---------- - ------------- - ------- - ------- -------------- -- ----- ------ -- - - --
  ------------- ---- -------- ----- ----- -- -
    --------------------------
  ---

这里我们将 \\RR 宏定义为实数集 $\mathbb

来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/45290