-
Notifications
You must be signed in to change notification settings - Fork 112
Expand file tree
/
Copy pathplugins-markdown.html
More file actions
136 lines (133 loc) · 7.18 KB
/
plugins-markdown.html
File metadata and controls
136 lines (133 loc) · 7.18 KB
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
130
131
132
133
134
135
136
<!DOCTYPE html>
<!-- THIS IS A GENERATED FILE. DO NOT EDIT. -->
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="description" content="Enable Markdown support in JSDoc.">
<title>Using the Markdown plugin – Use JSDoc</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>
<!--[if lt IE 9]>
<script src="scripts/html5shiv.min.js"></script>
<script src="scripts/html5shiv-printshiv.min.js"></script>
<![endif]-->
</head>
<body>
<header>
<a href="./index.html">@use JSDoc</a>
</header>
<article>
<h1>Using the Markdown plugin</h1>
<h2>Table of Contents</h2>
<ul>
<li>
<a href="#overview">Overview</a>
</li>
<li>
<a href="#enabling-the-markdown-plugin">Enabling the Markdown plugin</a>
</li>
<li>
<a href="#converting-markdown-in-additional-jsdoc-tags">Converting Markdown in additional JSDoc tags</a>
</li>
<li>
<a href="#excluding-the-default-tags-from-markdown-processing">Excluding the default tags from Markdown processing</a>
</li>
<li>
<a href="#hard-wrapping-text-at-line-breaks">Hard-wrapping text at line breaks</a>
</li>
<li>
<a href="#adding-id-attributes-to-headings">Adding ID attributes to headings</a>
</li>
</ul>
<h2 id="overview">Overview</h2>
<p>JSDoc includes a Markdown plugin that automatically converts Markdown-formatted text to HTML. You can use this plugin with any JSDoc template. In JSDoc 3.2.2
and later, the Markdown plugin uses the
<a href="https://github.com/chjj/marked">marked Markdown parser</a>.</p>
<p><strong>Note</strong>: When you enable the Markdown plugin, be sure to include a leading asterisk on each line of your JSDoc comments. If you omit the leading
asterisks, JSDoc's parser may remove asterisks that are used for Markdown formatting.</p>
<p>
<a name="default-tags"></a>
By default, JSDoc looks for Markdown-formatted text in the following JSDoc tags:</p>
<ul>
<li><a href="tags-author.html"><code>@author</code></a>
</li>
<li><a href="tags-classdesc.html"><code>@classdesc</code></a>
</li>
<li><a href="tags-description.html"><code>@description</code></a> (including untagged descriptions at the start of a JSDoc comment)
</li>
<li><a href="tags-param.html"><code>@param</code></a>
</li>
<li><a href="tags-property.html"><code>@property</code></a>
</li>
<li><a href="tags-returns.html"><code>@returns</code></a>
</li>
<li><a href="tags-see.html"><code>@see</code></a>
</li>
<li><a href="tags-throws.html"><code>@throws</code></a>
</li>
</ul>
<h2 id="enabling-the-markdown-plugin">Enabling the Markdown plugin</h2>
<p>To enable the Markdown plugin, add the string <code>plugins/markdown</code> to the <code>plugins</code> array in your
<a href="about-configuring-jsdoc.html">JSDoc configuration file</a>:</p>
<figure>
<figcaption>JSON configuration file that enables the Markdown plugin</figcaption><pre class="prettyprint lang-json"><code>{
"plugins": ["plugins/markdown"]
}
</code></pre>
</figure>
<h2 id="converting-markdown-in-additional-jsdoc-tags">Converting Markdown in additional JSDoc tags</h2>
<p>By default, the Markdown plugin only processes <a href="#default-tags">specific JSDoc tags</a> for Markdown text. You can handle Markdown text in other tags
by adding a <code>markdown.tags</code> property to your JSDoc configuration file. The <code>markdown.tags</code> property contains an array of the additional
doclet properties that can contain Markdown text. (In most cases, the name of the doclet property is the same as the tag name. However, some tags are stored
differently; for example, the <code>@param</code> tag is stored in a doclet's <code>params</code> property. If you're not sure how a tag's text
is stored in a doclet, run JSDoc with the <code>-X/--explain</code> tag, which prints each doclet to the console.)</p>
<p>For example, if the <code>foo</code> and <code>bar</code> tags accept values that are stored in a doclet's <code>foo</code> and <code>bar</code> properties,
you could enable Markdown processing of these tags by adding the following settings to your JSDoc configuration file:</p>
<figure>
<figcaption>Converting Markdown in 'foo' and 'bar' tags</figcaption><pre class="prettyprint lang-json"><code>{
"plugins": ["plugins/markdown"],
"markdown": {
"tags": ["foo", "bar"]
}
}
</code></pre>
</figure>
<h2 id="excluding-the-default-tags-from-markdown-processing">Excluding the default tags from Markdown processing</h2>
<p>To prevent the Markdown plugin from processing any of the <a href="#default-tags">default JSDoc tags</a>, add a
<code>markdown.excludeTags</code> property to your JSDoc configuration file. The <code>markdown.excludeTags</code> property contains an array of the default
tags that should not be processed for Markdown text.</p>
<p>For example, to exclude the <code>author</code> tag from Markdown processing:</p>
<figure>
<figcaption>Excluding the 'author' tag from Markdown processing</figcaption><pre class="prettyprint lang-json"><code>{
"plugins": ["plugins/markdown"],
"markdown": {
"excludeTags": ["author"]
}
}
</code></pre>
</figure>
<h2 id="hard-wrapping-text-at-line-breaks">Hard-wrapping text at line breaks</h2>
<p>By default, the Markdown plugin does not hard-wrap text at line breaks. This is because it's normal for a JSDoc comment to be wrapped across multiple lines.
If you prefer to hard-wrap text at line breaks, set your JSDoc configuration file's <code>markdown.hardwrap</code> property to <code>true</code>. This
property is available in JSDoc 3.4.0 and later.</p>
<h2 id="adding-id-attributes-to-headings">Adding ID attributes to headings</h2>
<p>By default, the Markdown plugin does not add an <code>id</code> attribute to each HTML heading. To automatically add <code>id</code> attributes based on the
heading's text, set your JSDoc configuration file's
<code>markdown.idInHeadings</code> property to <code>true</code>. This property is available in JSDoc 3.4.0 and later.</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-2017 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>
<script type="text/javascript">
prettyPrint();
</script>
</body>
</html>