forked from jsdoc/jsdoc.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
/
plugins-markdown.html
162 lines (154 loc) · 8.58 KB
/
plugins-markdown.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
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
<!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>Use JSDoc: Using the Markdown plugin</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="#how-to-use-the-markdown-plugin">How to use the Markdown plugin</a>
</li>
<li>
<a href="#configuring-the-markdown-plugin">Configuring the Markdown plugin</a>
</li>
<li>
<a href="#choosing-a-parser">Choosing a parser</a>
<ul>
<li>
<a href="#dominic-evilstreak-baggott-s-markdown-js">Dominic "evilstreak" Baggott's markdown-js</a>
</li>
<li>
<a href="#github-flavored-markdown">GitHub Flavored Markdown</a>
</li>
<li>
<a href="#why-two-parsers-">Why two parsers?</a>
</li>
</ul>
</li>
<li>
<a href="#extended-tag-support">Extended tag support</a>
</li>
</ul>
<h2 id="how-to-use-the-markdown-plugin">How to use the Markdown plugin</h2>
<p>For most users, all you need to do is add the plugin to your JSDoc configuration (<code>conf.json</code>) as you would any other, by adding a reference to it
in the "plugins" entry of the configuration JSON:</p>
<figure>
<figcaption>Example</figcaption><pre class="prettyprint"><code>...
"plugins": [ "plugins/markdown" ]
...
</code></pre>
</figure>
<p>This will cause Markdown in <code>@description</code> tags (including implicit descriptions without tags), <code>@classdesc</code> tags, <code>@param</code> tags, <code>@property</code> tags, and <code>@returns</code> tags to be parsed.</p>
<p>Also, be sure to use leading asterisks in your doc comments! If you omit the leading asterisks, JSDoc's code parser may remove other asterisks that are used
for Markdown formatting.</p>
<h2 id="configuring-the-markdown-plugin">Configuring the Markdown plugin</h2>
<p>The plugin also offers several configuration options for advanced users who want GitHub integration, extended tag support, etc. All configuration for the Markdown
plugin should be added to a <code>markdown</code> property in your JSDoc configuration:</p>
<figure>
<figcaption>Example</figcaption><pre class="prettyprint"><code>...
"plugins": [ "plugins/markdown" ],
"markdown": {
"opt1": "value",
"opt2": [ "foo", "bar", "baz" ]
}
...
</code></pre>
</figure>
<h2 id="choosing-a-parser">Choosing a parser</h2>
<p>The plugin currently supports two Markdown parsers. You can select which parser to use by adding a <code>parser</code> property to your Markdown configuration:</p>
<figure>
<figcaption>Example</figcaption><pre class="prettyprint"><code>...
"plugins": [ "plugins/markdown" ],
"markdown": {
"parser": "gfm"
}
...
</code></pre>
</figure>
<h3 id="dominic-evilstreak-baggott-s-markdown-js">Dominic "evilstreak" Baggott's markdown-js</h3>
<p>The default parser is Dominic Baggott's excellent <a href="https://github.com/evilstreak/markdown-js">markdown-js</a>. It can be explicitly selected by setting
the <code>parser</code> to <code>evilstreak</code> and has one additional (and optional) configuration option, <code>dialect</code>, which can be used to select
which of markdown-js' built-in dialects to use. If omitted, markdown-js' default dialect will be used.</p>
<figure>
<figcaption>Example</figcaption><pre class="prettyprint"><code>...
"plugins": [ "plugins/markdown" ],
"markdown": {
"parser": "evilstreak",
"dialect": "Maruku"
}
...
</code></pre>
</figure>
<h3 id="github-flavored-markdown">GitHub Flavored Markdown</h3>
<p>The alternative parser is the modified Showdown parser supplied by GitHub for their <a href="https://help.github.com/articles/github-flavored-markdown">GitHub Flavored Markdown (GFM)</a>.
GFM provides several enhancements to standard Markdown syntax (see its documentation) intended to be useful to developers. It <em>also</em> has the ability
to quickly link to GitHub repositories, files, and issues. It can be selected by setting the <code>parser</code> to <code>gfm</code> and supports three additional
(and optional) configuration options.</p>
<p>The <code>hardwrap</code> option controls the hard wrapping of line ends. Unlike standard Markdown, GFM considers a single newline to indicate a "hard break"
in the paragraph, but this doesn't work well with the line length limitations commonly used with comment documentation, so is disabled by default. If you
want to turn hard wrapping back on, set <code>hardwrap</code> to <code>true</code> (or any non-falsy value).</p>
<p>The <code>githubRepoName</code> and <code>githubRepoOwner</code> indicate which GitHub repo should be used for GitHub links which do not fully specify a repo.
These options have no effect unless used together and if they are omitted, several of GFM's default link types will be unavailable. Conversely, if you
supply both <code>github*</code> options but do not explicitly select <code>gfm</code> as your parser, it will be automatically selected for you.</p>
<figure>
<figcaption>Example</figcaption><pre class="prettyprint"><code>...
"plugins": [ "plugins/markdown" ],
"markdown": {
"parser": "gfm",
"hardwrap": true
}
...
</code></pre>
</figure>
<h3 id="why-two-parsers-">Why two parsers?</h3>
<p>The "evilstreak" parser is flexible, extensible, currently-maintained, and was the only parser available in earlier versions of the Markdown plugin,
but doesn't support the useful GFM extensions. The "gfm" parser is based on the no-longer-maintained Showdown parser, but it supports GFM extensions.</p>
<p>In the future, if GFM support is made available for the "evilstreak" parser, this plugin will drop the "gfm" parser in favor of that support.</p>
<h2 id="extended-tag-support">Extended tag support</h2>
<p>While the Markdown plugin already supports JSDoc's default tags, if you're using other plugins, you may well have extra tags available. You can tell
the Markdown plugin to handle those extra tags as well using the <code>tags</code> property, which is an array of the tags* it should check in addition to
the default set.</p>
<figure>
<figcaption>Example</figcaption><pre class="prettyprint"><code>...
"plugins": [ "plugins/markdown" ],
"markdown": {
"tags": [ "foo", "bars", "bazzes" ]
}
...
</code></pre>
</figure>
<p>Because the Markdown plugin works with JSDoc's internal representation rather than with the source comments, the names you need to enter in the <code>tags</code> property aren't necessarily the same as the actual tag names. For example, in the default set of tags, <code>@param</code> is stored under <code>params</code>.
If you are having trouble getting the Markdown plugin to work with your extra tags, either take a peek at the output of JSDoc's <code>--explain</code> command-line parameter (which displays the internal state which plugins work with) or ask the plugin author which "doclet properties" their plugin
uses. The Markdown plugin supports strings, arrays, and objects/subdoclets.</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-2014 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>