-
Notifications
You must be signed in to change notification settings - Fork 105
/
Copy pathabout-configuring-default-template.html
129 lines (126 loc) · 7 KB
/
about-configuring-default-template.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
<!DOCTYPE html>
<!-- THIS IS A GENERATED FILE. DO NOT EDIT. -->
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="description" content="How to configure the output from JSDoc's default template.">
<title>Use JSDoc: Configuring JSDoc's default template</title>
<link rel="stylesheet" href="styles/usejsdoc.css">
<link rel="stylesheet" href="styles/prettify.css">
<link rel="stylesheet" href="styles/css3-github-ribbon.css">
<script src="scripts/prettify.js"></script>
</head>
<body>
<header>
<a href="./index.html">@use JSDoc</a>
</header>
<article>
<h1>Configuring JSDoc's default template</h1>
<h2>Table of Contents</h2>
<ul>
<li>
<a href="#generating-pretty-printed-source-files">Generating pretty-printed source files</a>
</li>
<li>
<a href="#copying-static-files-to-the-output-directory">Copying static files to the output directory</a>
</li>
<li>
<a href="#showing-the-current-date-in-the-page-footer">Showing the current date in the page footer</a>
</li>
<li>
<a href="#showing-longnames-in-the-navigation-column">Showing longnames in the navigation column</a>
</li>
<li>
<a href="#overriding-the-default-templates-layout-file">Overriding the default template's layout file</a>
</li>
<li>
<a href="#related-links">Related Links</a>
</li>
</ul>
<p>JSDoc's default template provides several options that you can use to customize the appearance and
content of generated documentation.</p>
<p>To use these options, you must <a href="about-configuring-jsdoc.html">create a configuration file</a> for JSDoc and set the
appropriate options in the configuration file.</p>
<h2 id="generating-pretty-printed-source-files">Generating pretty-printed source files</h2>
<p>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.</p>
<p>To disable pretty-printed files, set the option <code>templates.default.outputSourceFiles</code> to <code>false</code>.
Using this option also removes links to your source files from the documentation. This option is
available in JSDoc 3.3.0 and later.</p>
<h2 id="copying-static-files-to-the-output-directory">Copying static files to the output directory</h2>
<p>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.</p>
<p>To copy additional static files to the output directory, use the following options:</p>
<ul>
<li><code>templates.default.staticFiles.include</code>: An array of paths whose contents should be copied to the
output directory. Subdirectories will be copied as well.</li>
<li><code>templates.default.staticFiles.exclude</code>: An array of paths that should <em>not</em> be copied to the
output directory.</li>
<li><code>templates.default.staticFiles.includePattern</code>: A regular expression indicating which files to
copy. If this property is not defined, all files will be copied.</li>
<li><code>templates.default.staticFiles.excludePattern</code>: A regular expression indicating which files to
skip. If this property is not defined, nothing will be skipped.</li>
</ul>
<figure>
<figcaption>Copying a directory of images to the output directory</figcaption>
<p>To copy all of the static files in <code>./myproject/static</code> to the output directory:</p>
<pre class="prettyprint lang-json"><code>{
"templates": {
"default": {
"staticFiles": {
"include": [
"./myproject/static"
]
}
}
}
}
</code></pre>
<p>If your static files directory contains the file <code>./myproject/static/img/screen.png</code>, you can
display the image in your docs by using the HTML tag <code><img src="img/screen.png"></code>.</p>
</figure>
<h2 id="showing-the-current-date-in-the-page-footer">Showing the current date in the page footer</h2>
<p>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
<code>templates.default.includeDate</code> to <code>false</code>.</p>
<h2 id="showing-longnames-in-the-navigation-column">Showing longnames in the navigation column</h2>
<p>By default, JSDoc's default template shows a shortened version of each symbol's name in the
navigation column. For example, the symbol <code>my.namespace.MyClass</code> would be displayed simply as
<code>MyClass</code>. To show the complete longname instead, set the option
<code>templates.default.useLongnameInNav</code> to <code>true</code>. This option is available in JSDoc 3.4.0 and later.</p>
<h2 id="overriding-the-default-templates-layout-file">Overriding the default template's layout file</h2>
<p>The default template uses a file named <code>layout.tmpl</code> 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 <code>layout.tmpl</code> file to
use, which allows you to load your own custom CSS and JavaScript files in addition to, or instead
of, the standard files.</p>
<p>To use this feature, set the option <code>templates.default.layoutFile</code> 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.</p>
<h2 id="related-links">Related Links</h2>
<p>
<a href="about-configuring-jsdoc.html">Configuring JSDoc with a configuration file</a>
</p>
</article>
<footer>
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">
<img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" /></a>
<br>
Copyright © 2011-2019 the
<a href="https://github.com/jsdoc3/jsdoc3.github.com/contributors">contributors</a> to the
JSDoc 3 documentation project.
<br>
This website is <a href="https://github.com/jsdoc3/jsdoc3.github.com">open source</a> and is
licensed under the <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">
Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.
</footer>
<p>
<a href="https://github.com/jsdoc3/jsdoc" class="github-ribbon">Fork me on GitHub</a>
</p>
<script type="text/javascript">
prettyPrint();
</script>
</body>
</html>