使用 Markdown 插件

概述

JSDoc 包含一个 Markdown 插件，可自动将 Markdown 格式文本转换为 HTML。您可以在任何 JSDoc 模板中使用此插件。在 JSDoc 3.2.2 及更高版本中，Markdown 插件使用 marked Markdown 解析器。

注意：启用 Markdown 插件时，请确保在 JSDoc 注释的每一行开头都包含一个星号。如果您省略了开头星号，JSDoc 的解析器可能会删除用于 Markdown 格式的星号。

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

• @author
• @classdesc
• @description（包括 JSDoc 注释开头的未标记描述）
• @param
• @property
• @returns
• @see
• @throws

启用 Markdown 插件

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

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

在其他 JSDoc 标签中转换 Markdown

默认情况下，Markdown 插件仅处理 特定 JSDoc 标签 的 Markdown 文本。您可以通过向 JSDoc 配置文件添加 markdown.tags 属性来处理其他标签中的 Markdown 文本。markdown.tags 属性包含一个数组，其中包含可以包含 Markdown 文本的其他文档属性。（在大多数情况下，文档属性的名称与标签名称相同。但是，某些标签的存储方式不同；例如，@param 标签存储在文档的 params 属性中。如果您不确定标签的文本是如何存储在文档中的，请使用 -X/--explain 标签运行 JSDoc，该标签会将每个文档打印到控制台。）

例如，如果 foo 和 bar 标签接受存储在文档的 foo 和 bar 属性中的值，您可以通过向 JSDoc 配置文件添加以下设置来启用对这些标签的 Markdown 处理

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

从 Markdown 处理中排除默认标签

要防止 Markdown 插件处理任何 默认 JSDoc 标签，请向 JSDoc 配置文件添加 markdown.excludeTags 属性。markdown.excludeTags 属性包含一个数组，其中包含不应处理 Markdown 文本的默认标签。

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

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

在换行符处硬换行文本

默认情况下，Markdown 插件不会在换行符处硬换行文本。这是因为 JSDoc 注释跨多行换行是正常的。如果您希望在换行符处硬换行文本，请将 JSDoc 配置文件的 markdown.hardwrap 属性设置为 true。此属性在 JSDoc 3.4.0 及更高版本中可用。

向标题添加 ID 属性

默认情况下，Markdown 插件不会向每个 HTML 标题添加 id 属性。要根据标题的文本自动添加 id 属性，请将 JSDoc 配置文件的 markdown.idInHeadings 属性设置为 true。此属性在 JSDoc 3.4.0 及更高版本中可用。