使用 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 格式的星号。

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

@author
@classdesc
@description（包括 JSDoc 注释开头的未标记描述）
@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 插件只处理特定的 JSDoc 标签的 Markdown 文本。你可以通过在 JSDoc 配置文件中添加 markdown.tags 属性来处理其他标签中的 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 标签，请在你的 JSDoc 配置文件中添加一个 markdown.excludeTags 属性。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.