跳到主要内容

使用Markdown插件

目录​

概述​

JSDoc 包括 Markdown 插件，自动把 Markdown 格式文本转换成 HTML。你可以在任何 JSDoc 模板中使用这个插件。在 JSDoc3.2.2 及以后版本中，Markdown 插件使用了marked Markdown 解析器。

注意：当您启用 Markdown 插件，一定要在 JSDoc 注释的每行前面加上前导星号。如果省略前导星号，JSDoc 解析器可能会删除用于 Markdown 格式化的星号。

默认情况下，JSDoc 会在以下 JSDoc 标签中查找 Markdown 格式的文本：

启用Markdown插件​

要启用 Markdown 插件，只要将字符串 plugins/markdown 添加到 JSDoc 配置文件的 plugins 数组中即可。

示例，配置文件启用 Markdown 插件：

{
  "plugins": ["plugins/markdown"]
}

在额外的JSDoc标签中转换Markdown​

默认情况下，Markdown 插件只处理特定 JSDoc 标签的 Markdown 文本。您可以通过添加一个 markdown.tags 属性到 JSDoc 配置文件中，来处理的其他标签中的 Markdown 文本。markdown.tags 属性包含一个额外的 doclet 属性的数组，这个 doclet 属性可以包含 Markdown 文本。 （在大多数情况下，doclet 属性的名称相同的标签名。然而，一些标签存储方式不一样;例如，@param 标签存储在的 doclet 的 params 属性。如果你不知道如何标签的文本存储在一个 doclet 中，运行 JSDoc 使用 -X/--explain，打印每个的doclet 到控制台）

例如，如果 foo 和 bar 标签接收在一个的 doclet 的 foo 和 bar 属性中存储值，你可以通过添加下面的设置到 JSDoc 配置文件，来使用 Markdown 处理这些标签。

转换’foo’和’bar’标签中的 Markdown:

{
  "plugins": ["plugins/markdown"],
  "markdown": {
    "tags": ["foo", "bar"]
  }
}

剔除Markdown默认处理的标签​

为了防止 Markdown 插件处理任何默认 JSDoc 标签，添加一个 markdown.excludeTags 属性到 JSDoc 配置文件。该 markdown.excludeTags 属性包含不应该被 Markdown 文本处理的默认标签数组。

例如，从 Markdown 处理排除 author 标签：

{
  "plugins": ["plugins/markdown"],
  "markdown": {
    "excludeTags": ["author"]
  }
}

用换行符换行文本​

默认情况下，Markdown 插件不处理换行符换行的文本。这是因为正常的 JSDoc 注释可以多行。如果更喜欢处理换行符换行的文本，设置 JSDoc 配置文件中的 markdown.hardwrap 属性为 true。此属性是在 JSDoc3.4.0 及更高版本中可用。

添加ID属性到标题标签​

默认情况下，Markdown 插件不会给每个 HTML 标题标签添加 id 属性。想要标题标签文本自动添加 ID 属性，设置 JSDoc 配置文件 markdown.idInHeadings 属性为 true。此属性是在 JSDoc3.4.0 及更高版本中可用。