JSDoc 中文网

配置 JSDoc 的默认模板

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

¥JSDoc's default template provides several options that you can use to customize the appearance and content of generated documentation.

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

¥To use these options, you must create a configuration file for JSDoc and set the appropriate options in the configuration file.

生成打印精美的源文件

¥Generating pretty-printed source files

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

¥By default, JSDoc's default template generates pretty-printed versions of your source files. It also links to these pretty-printed files in the documentation.

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

¥To disable pretty-printed files, set the option templates.default.outputSourceFiles to false. Using this option also removes links to your source files from the documentation. This option is available in JSDoc 3.3.0 and later.

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

¥Copying static files to the output directory

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

¥JSDoc's default template automatically copies a few static files, such as CSS stylesheets, to the output directory. In JSDoc 3.3.0 and later, you can tell the default template to copy additional static files to the output directory. For example, you might want to copy a directory of images to the output directory so you can display these images in your documentation.

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

¥To copy additional static files to the output directory, use the following options:

将图片目录复制到输出目录

将 ./myproject/static 中的所有静态文件复制到输出目录：

¥To copy all of the static files in ./myproject/static to the output directory:

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

如果你的静态文件目录包含文件 ./myproject/static/img/screen.png，你可以使用 HTML 标签 <img src="img/screen.png"> 在文档中显示该图片。

¥If your static files directory contains the file ./myproject/static/img/screen.png, you can display the image in your docs by using the HTML tag <img src="img/screen.png">.

在页脚中显示当前日期

¥Showing the current date in the page footer

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

¥By default, JSDoc's default template always shows the current date in the footer of the generated documentation. In JSDoc 3.3.0 and later, you can omit the current date by setting the option templates.default.includeDate to false.

在导航栏中显示长名称

¥Showing longnames in the navigation column

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

¥By default, JSDoc's default template shows a shortened version of each symbol's name in the navigation column. For example, the symbol my.namespace.MyClass would be displayed simply as MyClass. To show the complete longname instead, set the option templates.default.useLongnameInNav to true. This option is available in JSDoc 3.4.0 and later.

覆盖默认模板的布局文件

¥Overriding the default template's layout file

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

¥The default template uses a file named layout.tmpl to specify the header and footer for each page in the generated documentation. In particular, this file defines which CSS and JavaScript files are loaded for each page. In JSDoc 3.3.0 and later, you can specify your own layout.tmpl file to use, which allows you to load your own custom CSS and JavaScript files in addition to, or instead of, the standard files.

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

¥To use this feature, set the option templates.default.layoutFile to the path to your customized layout file. Relative paths are resolved against the current working directory; the path to the configuration file; and the JSDoc directory, in that order.