配置 JSDoc 的默认模板

JSDoc 的默认模板提供了多个选项，你可以使用这些选项来定制生成文档的外观和内容。

要使用这些选项，你必须 为 JSDoc 创建一个配置文件，并在配置文件中设置适当的选项。

生成漂亮打印的源文件

默认情况下，JSDoc 的默认模板会生成漂亮打印的源文件版本。它还会在文档中链接到这些漂亮打印的文件。

要禁用漂亮打印的文件，请将选项 templates.default.outputSourceFiles 设置为 false。使用此选项还会从文档中删除指向源文件的链接。此选项在 JSDoc 3.3.0 及更高版本中可用。

将静态文件复制到输出目录

JSDoc 的默认模板会自动将一些静态文件（如 CSS 样式表）复制到输出目录。在 JSDoc 3.3.0 及更高版本中，你可以告诉默认模板将其他静态文件复制到输出目录。例如，你可能希望将一个图像目录复制到输出目录，以便在文档中显示这些图像。

要将其他静态文件复制到输出目录，请使用以下选项

• templates.default.staticFiles.include：一个路径数组，其内容应复制到输出目录。子目录也将被复制。
• templates.default.staticFiles.exclude：一个路径数组，其中包含不应复制到输出目录的文件。
• templates.default.staticFiles.includePattern：一个正则表达式，表示要复制哪些文件。如果未定义此属性，则会复制所有文件。
• templates.default.staticFiles.excludePattern：一个正则表达式，表示要跳过哪些文件。如果未定义此属性，则不会跳过任何文件。

{
  "templates": {
    "default": {
      "staticFiles": {
        "include": [
        	"./myproject/static"
        ]
      }
    }
  }
}

在页脚中显示当前日期

默认情况下，JSDoc 的默认模板始终在生成文档的页脚中显示当前日期。在 JSDoc 3.3.0 及更高版本中，你可以通过将选项 templates.default.includeDate 设置为 false 来省略当前日期。

在导航栏中显示长名称

默认情况下，JSDoc 的默认模板在导航栏中显示每个符号名称的缩写版本。例如，符号 my.namespace.MyClass 将仅显示为 MyClass。要改为显示完整长名称，请将选项 templates.default.useLongnameInNav 设置为 true。此选项在 JSDoc 3.4.0 及更高版本中可用。

覆盖默认模板的布局文件

默认模板使用名为 layout.tmpl 的文件来指定生成文档中每个页面的页眉和页脚。特别是，此文件定义了为每个页面加载哪些 CSS 和 JavaScript 文件。在 JSDoc 3.3.0 及更高版本中，你可以指定要使用的自己的 layout.tmpl 文件，这允许你在标准文件之外或代替标准文件加载自己的自定义 CSS 和 JavaScript 文件。

要使用此功能，请将选项 templates.default.layoutFile 设置为自定义布局文件的路径。相对路径相对于当前工作目录、配置文件的路径和 JSDoc 目录（按此顺序）进行解析。

相关链接

• 使用配置文件配置 JSDoc