Skip to content

Commit 611ecbb

Browse files
tmcwtmcw
committed
feat(markdown): Add table of contents support for Markdown mode
Fixes #220
1 parent 2ae5d8f commit 611ecbb

File tree

116 files changed

+1029
-6
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

116 files changed

+1029
-6
lines changed

‎docs/NODE_API.md

+10
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,15 @@
11
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
22

3+
### Table of Contents
4+
5+
- [build](#build)
6+
- [buildSync](#buildsync)
7+
- [lint](#lint)
8+
- [formats](#formats)
9+
- [formats.html](#formatshtml)
10+
- [formats.markdown](#formatsmarkdown)
11+
- [formats.json](#formatsjson)
12+
313
## build
414

515
Generate JavaScript documentation as a list of parsed JSDoc

‎lib/commands/build.js

+6
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,11 @@ module.exports.builder = extend({},
2626
default: 'json',
2727
choices: ['json', 'md', 'remark', 'html']
2828
},
29+
'no-markdown-toc': {
30+
describe: 'include a table of contents in markdown output',
31+
default: 'stdout',
32+
type: 'boolean'
33+
},
2934
output: {
3035
describe: 'output location. omit for stdout, otherwise is a filename ' +
3136
'for single-file outputs and a directory name for multi-file outputs like html',
@@ -66,6 +71,7 @@ module.exports.handler = function build(argv, callback) {
6671
version: argv['project-version'] || (argv.package || {}).version,
6772
theme: argv.theme,
6873
paths: argv.paths,
74+
'no-markdown-toc': argv['no-markdown-toc'],
6975
hljs: argv.hljs || {}
7076
};
7177

‎lib/output/markdown.js

+3-1
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,9 @@ var remark = require('remark'),
2626
* });
2727
*/
2828
module.exports = function (comments, options, callback) {
29-
var processor = remark().use(toc);
29+
var processor = remark().use(toc, {
30+
tight: true
31+
});
3032
markdownAST(comments, options, function (err, ast) {
3133
var processedAST = processor.run(ast);
3234
return callback(null, processor.stringify(processedAST));

‎lib/output/markdown_ast.js

+11-5
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ var u = require('unist-builder'),
1414
* @param {Function} callback called with AST
1515
* @returns {undefined} calls callback
1616
*/
17-
function commentsToAST(comments, options, callback) {
17+
function markdownAST(comments, options, callback) {
1818

1919
// Configure code highlighting
2020
var hljsOptions = (options || {}).hljs || {},
@@ -33,6 +33,10 @@ function commentsToAST(comments, options, callback) {
3333
u('html', '<!-- Generated by documentation.js. Update this documentation by updating the source code. -->')
3434
];
3535

36+
var tableOfContentsHeading = [
37+
u('heading', { depth: 3 }, [u('text', 'Table of Contents')])
38+
];
39+
3640
/**
3741
* Generate an AST chunk for a comment at a given depth: this is
3842
* split from the main function to handle hierarchially nested comments
@@ -203,9 +207,11 @@ function commentsToAST(comments, options, callback) {
203207
}
204208

205209
return callback(null, rerouteLinks(linkerStack.link,
206-
u('root', generatorComment.concat(comments.reduce(function (memo, comment) {
207-
return memo.concat(generate(2, comment));
208-
}, [])))));
210+
u('root', generatorComment
211+
.concat(options['no-markdown-toc'] ? [] : tableOfContentsHeading)
212+
.concat(comments.reduce(function (memo, comment) {
213+
return memo.concat(generate(2, comment));
214+
}, [])))));
209215
}
210216

211-
module.exports = commentsToAST;
217+
module.exports = markdownAST;

‎test/fixture/auto_lang_hljs/multilanguage.output.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
22

3+
### Table of Contents
4+
5+
- [multilanguage.input](#multilanguageinput)
6+
37
## multilanguage.input
48

59
**Extends Foo, Bar**

‎test/fixture/boolean-literal-type.output.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
22

3+
### Table of Contents
4+
5+
- [f](#f)
6+
37
## f
48

59
**Parameters**

‎test/fixture/boolean-literal-type.output.md.json

+10
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,16 @@
55
"type": "html",
66
"value": "<!-- Generated by documentation.js. Update this documentation by updating the source code. -->"
77
},
8+
{
9+
"depth": 3,
10+
"type": "heading",
11+
"children": [
12+
{
13+
"type": "text",
14+
"value": "Table of Contents"
15+
}
16+
]
17+
},
818
{
919
"depth": 2,
1020
"type": "heading",

‎test/fixture/class.config.output.md

+7
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,12 @@
11
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
22

3+
### Table of Contents
4+
5+
- [MyClass](#myclass)
6+
- [getFoo](#getfoo)
7+
- [getUndefined](#getundefined)
8+
- [Hello](#hello)
9+
310
## MyClass
411

512
This is my class, a demo thing.

‎test/fixture/class.output.md

+6
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
22

3+
### Table of Contents
4+
5+
- [MyClass](#myclass)
6+
- [getFoo](#getfoo)
7+
- [getUndefined](#getundefined)
8+
39
## MyClass
410

511
This is my class, a demo thing.

‎test/fixture/class.output.md.json

+10
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,16 @@
55
"type": "html",
66
"value": "<!-- Generated by documentation.js. Update this documentation by updating the source code. -->"
77
},
8+
{
9+
"depth": 3,
10+
"type": "heading",
11+
"children": [
12+
{
13+
"type": "text",
14+
"value": "Table of Contents"
15+
}
16+
]
17+
},
818
{
919
"depth": 2,
1020
"type": "heading",

‎test/fixture/document-exported-export-default-object.output.md

+5
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
22

3+
### Table of Contents
4+
5+
- [document-exported-export-default-object.input](#document-exported-export-default-objectinput)
6+
- [x](#x)
7+
38
## document-exported-export-default-object.input
49

510
## x

‎test/fixture/document-exported-export-default-object.output.md.json

+10
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,16 @@
55
"type": "html",
66
"value": "<!-- Generated by documentation.js. Update this documentation by updating the source code. -->"
77
},
8+
{
9+
"depth": 3,
10+
"type": "heading",
11+
"children": [
12+
{
13+
"type": "text",
14+
"value": "Table of Contents"
15+
}
16+
]
17+
},
818
{
919
"depth": 2,
1020
"type": "heading",

‎test/fixture/document-exported-export-default-value.output.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
11
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
22

3+
### Table of Contents
4+
5+
- [document-exported-export-default-value.input](#document-exported-export-default-valueinput)
6+
37
## document-exported-export-default-value.input

‎test/fixture/document-exported-export-default-value.output.md.json

+10
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,16 @@
55
"type": "html",
66
"value": "<!-- Generated by documentation.js. Update this documentation by updating the source code. -->"
77
},
8+
{
9+
"depth": 3,
10+
"type": "heading",
11+
"children": [
12+
{
13+
"type": "text",
14+
"value": "Table of Contents"
15+
}
16+
]
17+
},
818
{
919
"depth": 2,
1020
"type": "heading",

‎test/fixture/document-exported.output.md

+33
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,38 @@
11
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
22

3+
### Table of Contents
4+
5+
- [z](#z)
6+
- [zMethod](#zmethod)
7+
- [x](#x)
8+
- [Class](#class)
9+
- [classMethod](#classmethod)
10+
- [classGetter](#classgetter)
11+
- [classSetter](#classsetter)
12+
- [staticMethod](#staticmethod)
13+
- [staticGetter](#staticgetter)
14+
- [staticSetter](#staticsetter)
15+
- [T5](#t5)
16+
- [y2Default](#y2default)
17+
- [y4](#y4)
18+
- [object](#object)
19+
- [prop](#prop)
20+
- [func](#func)
21+
- [method](#method)
22+
- [getter](#getter)
23+
- [setter](#setter)
24+
- [f1](#f1)
25+
- [f3](#f3)
26+
- [T](#t)
27+
- [T2](#t2)
28+
- [T4](#t4)
29+
- [f4](#f4)
30+
- [o1](#o1)
31+
- [om1](#om1)
32+
- [f5](#f5)
33+
- [o2](#o2)
34+
- [om2](#om2)
35+
336
## z
437

538
### zMethod

‎test/fixture/document-exported.output.md.json

+10
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,16 @@
55
"type": "html",
66
"value": "<!-- Generated by documentation.js. Update this documentation by updating the source code. -->"
77
},
8+
{
9+
"depth": 3,
10+
"type": "heading",
11+
"children": [
12+
{
13+
"type": "text",
14+
"value": "Table of Contents"
15+
}
16+
]
17+
},
818
{
919
"depth": 2,
1020
"type": "heading",

‎test/fixture/es6-class.output.md

+7
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,12 @@
11
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
22

3+
### Table of Contents
4+
5+
- [Foo](#foo)
6+
- [Bar](#bar)
7+
- [constructor](#constructor)
8+
- [bar](#bar-1)
9+
310
## Foo
411

512
**Extends React.Component**

‎test/fixture/es6-class.output.md.json

+10
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,16 @@
55
"type": "html",
66
"value": "<!-- Generated by documentation.js. Update this documentation by updating the source code. -->"
77
},
8+
{
9+
"depth": 3,
10+
"type": "heading",
11+
"children": [
12+
{
13+
"type": "text",
14+
"value": "Table of Contents"
15+
}
16+
]
17+
},
818
{
919
"depth": 2,
1020
"type": "heading",

‎test/fixture/es6-default2.output.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
22

3+
### Table of Contents
4+
5+
- [es6-default2.input](#es6-default2input)
6+
37
## es6-default2.input
48

59
**Parameters**

‎test/fixture/es6-default2.output.md.json

+10
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,16 @@
55
"type": "html",
66
"value": "<!-- Generated by documentation.js. Update this documentation by updating the source code. -->"
77
},
8+
{
9+
"depth": 3,
10+
"type": "heading",
11+
"children": [
12+
{
13+
"type": "text",
14+
"value": "Table of Contents"
15+
}
16+
]
17+
},
818
{
919
"depth": 2,
1020
"type": "heading",

‎test/fixture/es6-import.output.md

+6
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
22

3+
### Table of Contents
4+
5+
- [multiplyTwice](#multiplytwice)
6+
- [es6-ext](#es6-ext)
7+
- [simple.input](#simpleinput)
8+
39
## multiplyTwice
410

511
This function returns the number one.

‎test/fixture/es6-import.output.md.json

+10
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,16 @@
55
"type": "html",
66
"value": "<!-- Generated by documentation.js. Update this documentation by updating the source code. -->"
77
},
8+
{
9+
"depth": 3,
10+
"type": "heading",
11+
"children": [
12+
{
13+
"type": "text",
14+
"value": "Table of Contents"
15+
}
16+
]
17+
},
818
{
919
"depth": 2,
1020
"type": "heading",

0 commit comments

Comments
 (0)