使用 Markdown 插件

概述

¥Overview

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

¥JSDoc includes a Markdown plugin that automatically converts Markdown-formatted text to HTML. You can use this plugin with any JSDoc template. In JSDoc 3.2.2 and later, the Markdown plugin uses the marked Markdown parser.

注意：当你启用 Markdown 插件时，请务必在 JSDoc 注释的每一行中包含一个前导星号。如果省略前导星号，JSDoc 的解析器可能会删除用于 Markdown 格式的星号。

¥Note: When you enable the Markdown plugin, be sure to include a leading asterisk on each line of your JSDoc comments. If you omit the leading asterisks, JSDoc's parser may remove asterisks that are used for Markdown formatting.

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

¥ By default, JSDoc looks for Markdown-formatted text in the following JSDoc tags:

@author
@classdesc
@description（包括 JSDoc 评论开头的未标记描述）

¥@description (including untagged descriptions at the start of a JSDoc comment)
@param
@property
@returns
@see
@throws

启用 Markdown 插件

¥Enabling the Markdown plugin

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

¥To enable the Markdown plugin, add the string plugins/markdown to the plugins array in your JSDoc configuration file:

启用 Markdown 插件的 JSON 配置文件

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

在附加 JSDoc 标签中转换 Markdown

¥Converting Markdown in additional JSDoc tags

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

¥By default, the Markdown plugin only processes specific JSDoc tags for Markdown text. You can handle Markdown text in other tags by adding a markdown.tags property to your JSDoc configuration file. The markdown.tags property contains an array of the additional doclet properties that can contain Markdown text. (In most cases, the name of the doclet property is the same as the tag name. However, some tags are stored differently; for example, the @param tag is stored in a doclet's params property. If you're not sure how a tag's text is stored in a doclet, run JSDoc with the -X/--explain tag, which prints each doclet to the console.)

例如，如果 foo 和 bar 标记接受存储在 doclet 的 foo 和 bar 属性中的值，你可以通过将以下设置添加到 JSDoc 配置文件来启用这些标记的 Markdown 处理：

¥For example, if the foo and bar tags accept values that are stored in a doclet's foo and bar properties, you could enable Markdown processing of these tags by adding the following settings to your JSDoc configuration file:

在 'foo' 和 'bar' 标签中转换 Markdown

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

从 Markdown 处理中排除默认标签

¥Excluding the default tags from Markdown processing

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

¥To prevent the Markdown plugin from processing any of the default JSDoc tags, add a markdown.excludeTags property to your JSDoc configuration file. The markdown.excludeTags property contains an array of the default tags that should not be processed for Markdown text.

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

¥For example, to exclude the author tag from Markdown processing:

从 Markdown 处理中排除 'author' 标签

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

换行处的文本硬换行

¥Hard-wrapping text at line breaks

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

¥By default, the Markdown plugin does not hard-wrap text at line breaks. This is because it's normal for a JSDoc comment to be wrapped across multiple lines. If you prefer to hard-wrap text at line breaks, set your JSDoc configuration file's markdown.hardwrap property to true. This property is available in JSDoc 3.4.0 and later.

向标题添加 ID 属性

¥Adding ID attributes to headings

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

¥By default, the Markdown plugin does not add an id attribute to each HTML heading. To automatically add id attributes based on the heading's text, set your JSDoc configuration file's markdown.idInHeadings property to true. This property is available in JSDoc 3.4.0 and later.