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.