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.

注解

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格式的文本:

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

启用Markdown插件¶

To enable the Markdown plugin, add the string plugins/markdown to the plugins array in your 使用配置文件配置JSDoc:

JSON configuration file that enables the Markdown plugin¶

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

在其他JSDoc标记中转换Markdown¶

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 属性中的值, 你可以通过添加以下内容来启用这些标签的Markdown处理JSDoc配置文件的设置:

Converting Markdown in ‘foo’ and ‘bar’ tags¶

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

从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 标记:

Excluding the ‘author’ tag from Markdown processing¶

{
    "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及更高版本中可用.