Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit4c66fb1

Browse files
authored
feat(markdown): Add table of contents support for Markdown mode (#645)
Adds a new option, `--no-markdown-toc`, to turn off Table of Contents generation. Table of contents are now generated by default with markdown output, including through the `readme` command.Fixes#220
1 parent2ae5d8f commit4c66fb1

File tree

117 files changed

+6571
-161
lines changed

Some content is hidden

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

117 files changed

+6571
-161
lines changed

‎docs/NODE_API.md

Lines changed: 10 additions & 0 deletions
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

Lines changed: 6 additions & 0 deletions
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/commands/readme.js

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,8 @@ module.exports.builder = {
4242
example:'documentation readme index.js -s "API Docs" --github'
4343
};
4444

45+
functionnoop(){}
46+
4547
/**
4648
* Insert API documentation into a Markdown readme
4749
*@private
@@ -53,8 +55,7 @@ module.exports.handler = function readme(argv) {
5355
argv=sharedOptions.expandInputs(argv);
5456
argv.format='remark';
5557
/* eslint no-console: 0 */
56-
varlog=argv.q ?function(){}
57-
:console.log.bind(console,'[documentation-readme] ');
58+
varlog=argv.q ?noop :console.log.bind(console,'[documentation-readme] ');
5859
varreadmeFile=argv['readme-file'];
5960

6061
build.handler(argv,onAst);

‎lib/output/markdown.js

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
'use strict';
22

33
varremark=require('remark'),
4-
toc=require('remark-toc'),
54
markdownAST=require('./markdown_ast');
65

76
/**
@@ -26,9 +25,7 @@ var remark = require('remark'),
2625
* });
2726
*/
2827
module.exports=function(comments,options,callback){
29-
varprocessor=remark().use(toc);
3028
markdownAST(comments,options,function(err,ast){
31-
varprocessedAST=processor.run(ast);
32-
returncallback(null,processor.stringify(processedAST));
29+
returncallback(null,remark().stringify(ast));
3330
});
3431
};

‎lib/output/markdown_ast.js

Lines changed: 22 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
varu=require('unist-builder'),
2+
remark=require('remark'),
3+
toc=require('remark-toc'),
24
hljs=require('highlight.js'),
35
GithubSlugger=require('github-slugger'),
46
createLinkerStack=require('./util/linker_stack'),
@@ -14,7 +16,7 @@ var u = require('unist-builder'),
1416
*@param {Function} callback called with AST
1517
*@returns {undefined} calls callback
1618
*/
17-
functioncommentsToAST(comments,options,callback){
19+
functionmarkdownAST(comments,options,callback){
1820

1921
// Configure code highlighting
2022
varhljsOptions=(options||{}).hljs||{},
@@ -33,6 +35,10 @@ function commentsToAST(comments, options, callback) {
3335
u('html','<!-- Generated by documentation.js. Update this documentation by updating the source code. -->')
3436
];
3537

38+
vartableOfContentsHeading=[
39+
u('heading',{depth:3},[u('text','Table of Contents')])
40+
];
41+
3642
/**
3743
* Generate an AST chunk for a comment at a given depth: this is
3844
* split from the main function to handle hierarchially nested comments
@@ -202,10 +208,20 @@ function commentsToAST(comments, options, callback) {
202208
.filter(Boolean);
203209
}
204210

205-
returncallback(null,rerouteLinks(linkerStack.link,
206-
u('root',generatorComment.concat(comments.reduce(function(memo,comment){
207-
returnmemo.concat(generate(2,comment));
208-
},[])))));
211+
varroot=rerouteLinks(linkerStack.link,
212+
u('root',generatorComment
213+
.concat(options['no-markdown-toc'] ?[] :tableOfContentsHeading)
214+
.concat(comments.reduce(function(memo,comment){
215+
returnmemo.concat(generate(2,comment));
216+
},[]))));
217+
218+
if(!options['no-markdown-toc']){
219+
returnremark().use(toc,{
220+
tight:true
221+
}).run(root,callback);
222+
}
223+
224+
returncallback(null,root);
209225
}
210226

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

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

Lines changed: 4 additions & 0 deletions
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

Lines changed: 4 additions & 0 deletions
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

Lines changed: 57 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,53 @@
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+
"data": {
18+
"id":"table-of-contents",
19+
"htmlAttributes": {
20+
"id":"table-of-contents"
21+
},
22+
"hProperties": {
23+
"id":"table-of-contents"
24+
}
25+
}
26+
},
27+
{
28+
"type":"list",
29+
"ordered":false,
30+
"children": [
31+
{
32+
"type":"listItem",
33+
"loose":false,
34+
"children": [
35+
{
36+
"type":"paragraph",
37+
"children": [
38+
{
39+
"type":"link",
40+
"title":null,
41+
"url":"#f",
42+
"children": [
43+
{
44+
"type":"text",
45+
"value":"f"
46+
}
47+
]
48+
}
49+
]
50+
}
51+
]
52+
}
53+
]
54+
},
855
{
956
"depth":2,
1057
"type":"heading",
@@ -13,7 +60,16 @@
1360
"type":"text",
1461
"value":"f"
1562
}
16-
]
63+
],
64+
"data": {
65+
"id":"f",
66+
"htmlAttributes": {
67+
"id":"f"
68+
},
69+
"hProperties": {
70+
"id":"f"
71+
}
72+
}
1773
},
1874
{
1975
"type":"strong",

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

Lines changed: 7 additions & 0 deletions
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

Lines changed: 6 additions & 0 deletions
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.

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp