Skip to content

Commit 14a4d78

Browse files
hegemonichegemonic
committed
add page about configuring output from JSDoc's default template (#37, #47, #103, #107)
1 parent 38be5fe commit 14a4d78

6 files changed

+209
-4
lines changed

‎about-configuring-default-template.html

+111
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
<!DOCTYPE html>
2+
<!-- THIS IS A GENERATED FILE. DO NOT EDIT. -->
3+
<html lang="en">
4+
5+
<head>
6+
<meta charset="utf-8">
7+
<meta name="description" content="How to configure the output from JSDoc&#39;s default template.">
8+
<title>Use JSDoc: Configuring JSDoc&#39;s default template</title>
9+
<link rel="stylesheet" href="styles/usejsdoc.css">
10+
<link rel="stylesheet" href="styles/prettify.css">
11+
<link rel="stylesheet" href="styles/css3-github-ribbon.css">
12+
<script src="scripts/prettify.js"></script>
13+
<!--[if lt IE 9]>
14+
<script src="scripts/html5shiv.min.js"></script>
15+
<script src="scripts/html5shiv-printshiv.min.js"></script>
16+
<![endif]-->
17+
</head>
18+
19+
<body>
20+
<header>
21+
<a href="./index.html">@use JSDoc</a>
22+
</header>
23+
<article>
24+
<h1>Configuring JSDoc&#39;s default template</h1>
25+
<h2>Table of Contents</h2>
26+
<ul>
27+
<li>
28+
<a href="#generating-pretty-printed-source-files">Generating pretty-printed source files</a>
29+
</li>
30+
<li>
31+
<a href="#copying-static-files-to-the-output-directory">Copying static files to the output directory</a>
32+
</li>
33+
<li>
34+
<a href="#showing-the-current-date-in-the-page-footer">Showing the current date in the page footer</a>
35+
</li>
36+
<li>
37+
<a href="#overriding-the-default-template-s-layout-file">Overriding the default template&#39;s layout file</a>
38+
</li>
39+
<li>
40+
<a href="#related-links">Related Links</a>
41+
</li>
42+
</ul>
43+
<p>JSDoc&#39;s default template provides several options that you can use to customize the appearance and content of generated documentation.</p>
44+
<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
45+
file.</p>
46+
<h2 id="generating-pretty-printed-source-files">Generating pretty-printed source files</h2>
47+
<p>By default, JSDoc&#39;s default template generates pretty-printed versions of your source files. It also links to these pretty-printed files in the documentation.</p>
48+
<p>To disable pretty-printed files, set the option <code>templates.default.outputSourceFiles</code> to <code>false</code>. Using this option also removes links
49+
to your source files from the documentation. This option is available in JSDoc 3.3.0 and later.</p>
50+
<h2 id="copying-static-files-to-the-output-directory">Copying static files to the output directory</h2>
51+
<p>JSDoc&#39;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
52+
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
53+
so you can display these images in your documentation.</p>
54+
<p>To copy additional static files to the output directory, use the following options:</p>
55+
<ul>
56+
<li><code>templates.default.staticFiles.include</code>: An array of paths whose contents should be copied to the output directory. Subdirectories will be copied
57+
as well.</li>
58+
<li><code>templates.default.staticFiles.exclude</code>: An array of paths that should <em>not</em> be copied to the output directory.</li>
59+
<li><code>templates.default.staticFiles.includePattern</code>: A regular expression indicating which files to copy. If this property is not defined, all files
60+
will be copied.</li>
61+
<li><code>templates.default.staticFiles.excludePattern</code>: A regular expression indicating which files to skip. If this property is not defined, nothing will
62+
be skipped.</li>
63+
</ul>
64+
<figure>
65+
<figcaption>Copying a directory of images to the output directory</figcaption>
66+
<p>To copy all of the static files in <code>./myproject/static</code> to the output directory:</p>
67+
<pre class="prettyprint lang-json"><code>{
68+
"templates": {
69+
"default": {
70+
"staticFiles": {
71+
"include": [
72+
"./myproject/static"
73+
]
74+
}
75+
}
76+
}
77+
}
78+
</code></pre>
79+
<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
80+
<code>&lt;img src=&quot;img/screen.png&quot;&gt;</code>.</p>
81+
</figure>
82+
<h2 id="showing-the-current-date-in-the-page-footer">Showing the current date in the page footer</h2>
83+
<p>By default, JSDoc&#39;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
84+
current date by setting the option
85+
<code>templates.default.includeDate</code> to <code>false</code>.</p>
86+
<h2 id="overriding-the-default-template-s-layout-file">Overriding the default template&#39;s layout file</h2>
87+
<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,
88+
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
89+
to use, which allows you to load your own custom CSS and JavaScript files in addition to, or instead of, the standard files.</p>
90+
<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
91+
the path to the <code>config.json</code> file; the current working directory; and the JSDoc directory, in that order.</p>
92+
<h2 id="related-links">Related Links</h2>
93+
<p>
94+
<a href="about-configuring-jsdoc.html">Configuring JSDoc with conf.json</a>
95+
</p>
96+
</article>
97+
<footer>
98+
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">
99+
<img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" />
100+
</a>
101+
<br> Copyright &#169; 2011-2014 the
102+
<a href="https://github.com/jsdoc3/jsdoc3.github.com/contributors">contributors</a> to the JSDoc 3 documentation project.
103+
<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/">
104+
Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.
105+
</footer>
106+
<script type="text/javascript">
107+
prettyPrint();
108+
</script>
109+
</body>
110+
111+
</html>

‎about-configuring-jsdoc.html

+3-2
Original file line numberDiff line numberDiff line change
@@ -195,8 +195,9 @@ <h2 id="plugins">Plugins</h2>
195195
<p>The Markdown plugin can be configured by including a &quot;markdown&quot; object into conf.json; see
196196
<a href="plugins-markdown.html">Configuring the Markdown Plugin</a> for further information.</p>
197197
<h2 id="output-style-configuration">Output style configuration</h2>
198-
<p>The options in <code>templates</code> affect how JSDoc&#39;s output looks (although custom templates may not be affected by these, depending on how they are
199-
coded).</p>
198+
<p>The options in <code>templates</code> affect the appearance and content of generated documentation. Custom templates may not implement all of these options.
199+
See <a href="about-configuring-default-template.html">Configuring JSDoc&#39;s Default
200+
Template</a> for additional options that the default template supports.</p>
200201
<figure><pre class="prettyprint lang-js"><code>"templates": {
201202
"cleverLinks": false,
202203
"monospaceLinks": false

‎content/en/about-configuring-default-template.md

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
title: Configuring JSDoc's default template
3+
description: How to configure the output from JSDoc's default template.
4+
related:
5+
- about-configuring-jsdoc.html
6+
---
7+
8+
JSDoc's default template provides several options that you can use to customize the appearance and
9+
content of generated documentation.
10+
11+
To use these options, you must [create a configuration file][about-config] for JSDoc and set the
12+
appropriate options in the configuration file.
13+
14+
[about-config]: about-configuring-jsdoc.html
15+
16+
17+
## Generating pretty-printed source files
18+
19+
By default, JSDoc's default template generates pretty-printed versions of your source files. It also
20+
links to these pretty-printed files in the documentation.
21+
22+
To disable pretty-printed files, set the option `templates.default.outputSourceFiles` to `false`.
23+
Using this option also removes links to your source files from the documentation. This option is
24+
available in JSDoc 3.3.0 and later.
25+
26+
27+
## Copying static files to the output directory
28+
29+
JSDoc's default template automatically copies a few static files, such as CSS stylesheets, to the
30+
output directory. In JSDoc 3.3.0 and later, you can tell the default template to copy additional
31+
static files to the output directory. For example, you might want to copy a directory of images to
32+
the output directory so you can display these images in your documentation.
33+
34+
To copy additional static files to the output directory, use the following options:
35+
36+
+ `templates.default.staticFiles.include`: An array of paths whose contents should be copied to the
37+
output directory. Subdirectories will be copied as well.
38+
+ `templates.default.staticFiles.exclude`: An array of paths that should _not_ be copied to the
39+
output directory.
40+
+ `templates.default.staticFiles.includePattern`: A regular expression indicating which files to
41+
copy. If this property is not defined, all files will be copied.
42+
+ `templates.default.staticFiles.excludePattern`: A regular expression indicating which files to
43+
skip. If this property is not defined, nothing will be skipped.
44+
45+
{% example "Copying a directory of images to the output directory" %}
46+
47+
To copy all of the static files in `./myproject/static` to the output directory:
48+
49+
```json
50+
{
51+
"templates": {
52+
"default": {
53+
"staticFiles": {
54+
"include": [
55+
"./myproject/static"
56+
]
57+
}
58+
}
59+
}
60+
}
61+
```
62+
63+
If your static files directory contains the file `./myproject/static/img/screen.png`, you can
64+
display the image in your docs by using the HTML tag `<img src="img/screen.png">`.
65+
66+
{% endexample %}
67+
68+
69+
## Showing the current date in the page footer
70+
71+
By default, JSDoc's default template always shows the current date in the footer of the generated
72+
documentation. In JSDoc 3.3.0 and later, you can omit the current date by setting the option
73+
`templates.default.includeDate` to `false`.
74+
75+
76+
## Overriding the default template's layout file
77+
78+
The default template uses a file named `layout.tmpl` to specify the header and footer for each
79+
page in the generated documentation. In particular, this file defines which CSS and JavaScript files
80+
are loaded for each page. In JSDoc 3.3.0 and later, you can specify your own `layout.tmpl` file to
81+
use, which allows you to load your own custom CSS and JavaScript files in addition to, or instead
82+
of, the standard files.
83+
84+
To use this feature, set the option `templates.default.layoutFile` to the path to your customized
85+
layout file. Relative paths are resolved against the path to the `config.json` file; the current
86+
working directory; and the JSDoc directory, in that order.

‎content/en/about-configuring-jsdoc.md

+4-2
Original file line numberDiff line numberDiff line change
@@ -221,8 +221,9 @@ The Markdown plugin can be configured by including a "markdown" object into conf
221221

222222
## Output style configuration
223223

224-
The options in `templates` affect how JSDoc's output looks (although custom templates may not be
225-
affected by these, depending on how they are coded).
224+
The options in `templates` affect the appearance and content of generated documentation. Custom
225+
templates may not implement all of these options. See [Configuring JSDoc's Default
226+
Template][default-template] for additional options that the default template supports.
226227

227228
{% example %}
228229

@@ -247,6 +248,7 @@ Also, there are {@linkcode ...} and {@linkplain ...} if one wishes to force the
247248
in monospace or normal font respectively (see [@link, @linkcode and @linkplain][link-tag] for
248249
further information).
249250

251+
[default-template]: about-configuring-default-template.html
250252
[link-tag]: tags-inline-link.html
251253

252254

‎data/toc.json

+3
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,9 @@
1212
{
1313
"filename": "about-configuring-jsdoc.html"
1414
},
15+
{
16+
"filename": "about-configuring-default-template.html"
17+
},
1518
{
1619
"filename": "about-block-inline-tags.html"
1720
},

‎index.html

+2
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ <h2>Getting Started</h2>
3232
<dd>About command-line arguments to JSDoc.</dd>
3333
<dt><a href="about-configuring-jsdoc.html">Configuring JSDoc with conf.json</a></dt>
3434
<dd>How to configure JSDoc using a configuration file.</dd>
35+
<dt><a href="about-configuring-default-template.html">Configuring JSDoc&#39;s default template</a></dt>
36+
<dd>How to configure the output from JSDoc&#39;s default template.</dd>
3537
<dt><a href="about-block-inline-tags.html">Block and inline tags</a></dt>
3638
<dd>Overview of block and inline JSDoc tags.</dd>
3739
<dt><a href="about-plugins.html">About JSDoc plugins</a></dt>

0 commit comments

Comments
 (0)