8000 update Markdown docs to reflect changes in JSDoc >=3.2.0 (#38) · removed-usr/jsdoc.github.io@d2c7a77 · GitHub
[go: up one dir, main page]
Skip to content

Commit d2c7a77

Browse files
hegemonichegemonic
committed
update Markdown docs to reflect changes in JSDoc >=3.2.0 (jsdoc#38)
1 parent 7d6f3c5 commit d2c7a77

File tree

2 files changed

+136
-237
lines changed

2 files changed

+136
-237
lines changed

‎content/en/plugins-markdown.md

Lines changed: 77 additions & 132 deletions
Original file line numberDiff line numberDiff line change
@@ -3,158 +3,103 @@ title: Using the Markdown plugin
33
description: Enable Markdown support in JSDoc.
44
---
55

6-
## How to use the Markdown plugin
7-
8-
For most users, all you need to do is add the plugin to your JSDoc configuration (`conf.json`) as
9-
you would any other, by adding a reference to it in the "plugins" entry of the configuration JSON:
10-
11-
{% example "Example" %}
12-
13-
```
14-
...
15-
"plugins": [ "plugins/markdown" ]
16-
...
17-
```
18-
{% endexample %}
19-
20-
This will cause Markdown in `@description` tags (including implicit descriptions without tags),
21-
`@classdesc` tags, `@param` tags, `@property` tags, and `@returns` tags to be parsed.
22-
23-
Also, be sure to use leading asterisks in your doc comments! If you omit the leading asterisks,
24-
JSDoc's code parser may remove other asterisks that are used for Markdown formatting.
25-
26-
## Configuring the Markdown plugin
27-
28-
The plugin also offers several configuration options for advanced users who want GitHub integration,
29-
extended tag support, etc. All configuration for the Markdown plugin should be added to a
30-
`markdown` property in your JSDoc configuration:
31-
32-
{% example "Example" %}
33-
34-
35-
```
36-
...
37-
"plugins": [ "plugins/markdown" ],
38-
39-
"markdown": {
40-
"opt1": "value",
41-
"opt2": [ "foo", "bar", "baz" ]
6+
## Overview
7+
8+
JSDoc includes a Markdown plugin that automatically converts Markdown-formatted text to HTML. You
9+
can use this plugin with any JSDoc template. In JSDoc 3.2.2 and later, the Markdown plugin uses the
10+
[marked Markdown parser][marked].
11+
12+
**Note**: When you enable the Markdown plugin, be sure to include a leading asterisk on each line of
13+
your JSDoc comments. If you omit the leading asterisks, JSDoc's parser may remove asterisks that are
14+
used for Markdown formatting.
15+
16+
<a name="default-tags"></a>
17+
By default, JSDoc looks for Markdown-formatted text in the following JSDoc tags:
18+
19+
+ [`@author`][author-tag]
20+
+ [`@classdesc`][classdesc-tag]
21+
+ [`@description`][description-tag] (including untagged descriptions at the start of a JSDoc
22+
comment)
23+
+ [`@param`][param-tag]
24+
+ [`@property`][property-tag]
25+
+ [`@returns`][returns-tag]
26+
+ [`@see`][see-tag]
27+
+ [`@throws`][throws-tag]
28+
29+
[additional-tags]: #additional-tags
30+
[author-tag]: tags-author.html
31+
[classdesc-tag]: tags-classdesc.html
32+
[description-tag]: tags-description.html
33+
[marked]: https://github.com/chjj/marked
34+
[param-tag]: tags-param.html
35+
[property-tag]: tags-property.html
36+
[returns-tag]: tags-returns.html
37+
[see-tag]: tags-see.html
38+
[throws-tag]: tags-throws.html
39+
40+
41+
## Enabling the Markdown plugin
42+
43+
To enable the Markdown plugin, add the string `plugins/markdown` to the `plugins` property in your
44+
[JSDoc configuration file][config-file]:
45+
46+
{% example "Configuration file that enables the Markdown plugin" %}
47+
48+
```json
49+
{
50+
"plugins": ["plugins/markdown"]
4251
}
43-
...
4452
```
4553
{% endexample %}
4654

47-
## Choosing a parser
55+
[config-file]: about-configuring-jsdoc.html
4856

49-
The plugin currently supports two Markdown parsers. You can select which parser to use by adding a
50-
`parser` property to your Markdown configuration:
5157

52-
{% example "Example" %}
58+
## Converting Markdown in additional JSDoc tags
5359

54-
```
55-
...
56-
"plugins": [ "plugins/markdown" ],
57-
58-
"markdown": {
59-
"parser": "gfm"
60-
}
61-
...
62-
```
63-
{% endexample %}
60+
By default, the Markdown plugin only processes [specific JSDoc tags][default-tags] for Markdown
61+
text. You can handle Markdown text in other tags by adding a `markdown.tags` property to your JSDoc
62+
configuration file. The `markdown.tags` property contains an array of the additional doclet
63+
properties that can contain Markdown text. (In most cases, the name of the doclet property is the
64+
same as the tag name. However, some tags are stored differently; for example, the `@param` tag is
65+
stored in a doclet's `params` property. If you're not sure how a tag's text is stored in a doclet,
66+
run JSDoc with the `-X/--explain` tag, which prints each doclet to the console.)
6467

65-
### Dominic "evilstreak" Baggott's markdown-js
68+
For example, if the `foo` and `bar` tags accept values that are stored in a doclet's `foo` and `bar`
69+
properties, you could enable Markdown processing of these tags by adding the following settings to
70+
your JSDoc configuration file:
6671

67-
The default parser is Dominic Baggott's excellent [markdown-js][]. It can be explicitly selected by
68-
setting the `parser` to `evilstreak` and has one additional (and optional) configuration option,
69-
`dialect`, which can be used to select which of markdown-js' built-in dialects to use. If omitted,
70-
markdown-js' default dialect will be used.
72+
{% example "Converting Markdown in 'foo' and 'bar' tags" %}
7173

72-
{% example "Example" %}
73-
74-
```
75-
...
76-
"plugins": [ "plugins/markdown" ],
77-
78-
"markdown": {
79-
"parser": "evilstreak",
80-
"dialect": "Maruku"
74+
```json
75+
{
76+
"plugins": ["plugins/markdown"],
77+
"markdown": {
78+
"tags": ["foo", "bar"]
79+
}
8180
}
82-
...
8381
```
8482
{% endexample %}
8583

86-
[markdown-js]: https://github.com/evilstreak/markdown-js
84+
[default-tags]: #default-tags
8785

88-
### GitHub Flavored Markdown
8986

90-
The alternative parser is the modified Showdown parser supplied by GitHub for their [GitHub Flavored
91-
Markdown (GFM)][gfm]. GFM provides several enhancements to standard Markdown syntax (see its
92-
documentation) intended to be useful to developers. It _also_ has the ability to quickly link to
93-
GitHub repositories, files, and issues. It can be selected by setting the `parser` to `gfm` and
94-
supports three additional (and optional) configuration options.
87+
## Excluding the default tags from Markdown processing
9588

96-
The `hardwrap` option controls the hard wrapping of line ends. Unlike standard Markdown, GFM
97-
considers a single newline to indicate a "hard break" in the paragraph, but this doesn't work well
98-
with the line length limitations commonly used with comment documentation, so is disabled by
99-
default. If you want to turn hard wrapping back on, set `hardwrap` to `true` (or any non-falsy
100-
value).
89+
To prevent the Markdown plugin from processing any of the [default JSDoc tags][default-tags], add a
90+
`markdown.excludeTags` property to your JSDoc configuration file. The `markdown.excludeTags`
91+
property contains an array of the default tags that should not be processed for Markdown text.
10192

102-
The `githubRepoName` and `githubRepoOwner` indicate which GitHub repo should be used for GitHub
103-
links which do not fully specify a repo. These options have no effect unless used together and if
104-
they are omitted, several of GFM's default link types will be unavailable. Conversely, if you
105-
supply both `github*` options but do not explicitly select `gfm` as your parser, it will be
106-
automatically selected for you.
93+
For example, to exclude the `author` tag from Markdown processing:
10794

108-
{% example "Example" %}
109-
110-
```
111-
...
112-
"plugins": [ "plugins/markdown" ],
95+
{% example "Excluding the 'author' tag from Markdown processing" %}
11396

114-
"markdown": {
115-
"parser": "gfm",
116-
"hardwrap": true
97+
```json
98+
{
99+
"plugins": ["plugins/markdown"],
100+
"markdown": {
101+
"excludeTags": ["author"]
102+
}
117103
}
118-
...
119104
```
120105
{% endexample %}
121-
122-
[gfm]: https://help.github.com/articles/github-flavored-markdown/
123-
124-
### Why two parsers?
125-
126-
The "evilstreak" parser is flexible, extensible, currently-maintained, and was the only parser
127-
available in earlier versions of the Markdown plugin, but doesn't support the useful GFM extensions.
128-
The "gfm" parser is based on the no-longer-maintained Showdown parser, but it supports GFM
129-
extensions.
130-
131-
In the future, if GFM support is made available for the "evilstreak" parser, this plugin will drop
132-
the "gfm" parser in favor of that support.
133-
134-
## Extended tag support
135-
136-
While the Markdown plugin already supports JSDoc's default tags, if you're using other plugins, you
137-
may well have extra tags available. You can tell the Markdown plugin to handle those extra tags as
138-
well using the `tags` property, which is an array of the tags* it should check in addition to the
139-
default set.
140-
141-
{% example "Example" %}
142-
143-
```
144-
...
145-
"plugins": [ "plugins/markdown" ],
146-
147-
"markdown": {
148-
"tags": [ "foo", "bars", "bazzes" ]
149-
}
150-
...
151-
```
152-
{% endexample %}
153-
154-
Because the Markdown plugin works with JSDoc's internal representation rather than with the source
155-
comments, the names you need to enter in the `tags` property aren't necessarily the same as the
156-
actual tag names. For example, in the default set of tags, `@param` is stored under `params`. If
157-
you are having trouble getting the Markdown plugin to work with your extra tags, either take a peek
158-
at the output of JSDoc's `--explain` command-line parameter (which displays the internal state which
159-
plugins work with) or ask the plugin author which "doclet properties" their plugin uses. The
160-
Markdown plugin supports strings, arrays, and objects/subdoclets.

0 commit comments

Comments
 (0)
0