8000 Markdown table support. Fixes #321 · developmentseed/documentation@69af721 · GitHub
[go: up one dir, main page]
Skip to content

Commit 69af721

Browse files
tmcwtmcw
committed
Markdown table support. Fixes documentationjs#321 
1 parent 6cbf4bd commit 69af721

File tree

4 files changed

+113
-35
lines changed

4 files changed

+113
-35
lines changed

‎lib/commands/build.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ function build(documentation, parsedArgs, callback) {
5353
name: buildOptions.name || (options.package || {}).name,
5454
version: buildOptions['project-version'] || (options.package || {}).version,
5555
theme: buildOptions.theme,
56+
markdownTables: buildOptions['markdown-tables'],
5657
hljs: options.hljs || {}
5758
};
5859

‎lib/commands/shared_options.js

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,10 @@ function sharedOutputOptions(parser) {
7979
.option('project-version', {
8080
describe: 'project version. by default, inferred from package.json'
8181
})
82+
.option('markdown-tables', {
83+
type: 'boolean',
84+
describe: 'format parameters and properties as lists in markdown'
85+
})
8286
.help('help');
8387
}
8488

‎lib/output/markdown_ast.js

Lines changed: 84 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,43 @@
11
var u = require('unist-builder'),
22
hljs = require('highlight.js'),
33
GithubSlugger = require('github-slugger'),
4+
unnest = require('../unnest'),
45
createLinkerStack = require('./util/linker_stack'),
56
rerouteLinks = require('./util/reroute_links'),
67
_formatType = require('./util/format_type');
78

9+
/**
10+
* Format a list of left, right items into a remark AST list
11+
*
12+
* @param {Array<{ left: Array<Object>, left: Array<Object> }>} items left, right pairs
13+
* @returns {Object} markdown AST
14+
*/
15+
function list(items) {
16+
return u('list', { ordered: false }, items.map(function (item) {
17+
return u('listItem', u('paragraph', item.left.concat(item.right || [])));
18+
}));
19+
}
20+
21+
/**
22+
* Format a list of left, right items into a remark AST table
23+
*
24+
* @param {Array<{ left: Array<Object>, left: Array<Object> }>} items left, right pairs
25+
* @param {Array<string>} headers column headers
26+
* @returns {Object} markdown AST
27+
*/
28+
function table(items, headers) {
29+
return u('table', { align: 'left' },
30+
[u('tableRow', headers.map(function (header) {
31+
return u('tableCell', [u('text', header)]);
32+
}))]
33+
.concat(items.map(function (item) {
34+
return u('tableRow', [
35+
u('tableCell', u('paragraph', item.left)),
36+
u('tableCell', u('paragraph', item.right))
37+
]);
38+
})));
39+
}
40+
841
/**
942
* Given a hierarchy-nested set of comments, generate an remark-compatible
1043
* Abstract Syntax Tree usable for generating Markdown output
@@ -29,6 +62,31 @@ function commentsToAST(comments, options, callback) {
2962

3063
var formatType = _formatType.bind(undefined, linkerStack.link);
3164

65+
var listFormatter = list;
66+
if (options.markdownTables) {
67+
listFormatter = table;
68+
}
69+
70+
function genericFormatRight(param) {
71+
return (param.description ? param.description.children[0].children : [])
72+
.concat([
73+
!!param.default && u('paragraph', [
74+
u('text', ' (optional, default '),
75+
u('inlineCode', param.default),
76+
u('text', ')')
77+
])
78+
]);
79+
}
80+
81+
function genericFormatLeft(tag) {
82+
return [
83+
u('inlineCode', tag.name),
84+
u('text', ' '),
85+
!!tag.type && u('strong', formatType(tag.type)),
86+
u('text', ' ')
87+
].filter(Boolean);
88+
}
89+
3290
/**
3391
* Generate an AST chunk for a comment at a given depth: this is
3492
* split from the main function to handle hierarchially nested comments
@@ -40,24 +98,14 @@ function commentsToAST(comments, options, callback) {
4098
function generate(depth, comment) {
4199

42100
function paramList(params) {
43-
return u('list', { ordered: false }, params.map(function (param) {
44-
return u('listItem', [
45-
u('paragraph', [
46-
u('inlineCode', param.name),
47-
u('text', ' '),
48-
!!param.type && u('strong', formatType(param.type)),
49-
u('text', ' ')
50-
].concat(param.description ? param.description.children : [])
51-
.concat([
52-
!!param.default && u('paragraph', [
53-
u('text', ' (optional, default '),
54-
u('inlineCode', param.default),
55-
u('text', ')')
56-
])
57-
]).filter(Boolean))
58-
].concat(param.properties && paramList(param.properties))
59-
.filter(Boolean));
60-
}));
101+
return listFormatter(params.map(function (param) {
102+
return {
103+
left: genericFormatLeft(param),
104+
right: genericFormatRight(param)
105+
.concat(param.properties && paramList(param.properties))
106+
.filter(Boolean)
107+
};
108+
}), ['Parameter', 'Description']);
61109
}
62110

63111
function paramSection(comment) {
@@ -75,20 +123,14 @@ function commentsToAST(comments, options, callback) {
75123
}
76124

77125
function propertyList(properties) {
78-
return u('list', { ordered: false },
79-
properties.map(function (property) {
80-
return u('listItem', [
81-
u('paragraph', [
82-
u('inlineCode', property.name),
83-
u('text', ' '),
84-
u('strong', formatType(property.type)),
85-
u('text', ' ')
86-
]
87-
.concat(property.description ? property.description.children: [])
88-
.filter(Boolean)),
89-
property.properties && propertyList(property.properties)
90-
].filter(Boolean));
91-
}));
126+
return listFormatter(properties.map(function (property) {
127+
return {
128+
left: genericFormatLeft(property),
129+
right: genericFormatRight(property)
130+
.concat(property.properties && propertyList(property.properties))
131+
.filter(Boolean)
132+
};
133+
}), ['Property', 'Description']);
92134
}
93135

94136
function examplesSection(comment) {
@@ -190,9 +232,16 @@ function commentsToAST(comments, options, callback) {
190232
}
191233

192234
return callback(null, rerouteLinks(linkerStack.link,
193-
u('root', comments.reduce(function (memo, comment) {
194-
return memo.concat(generate(1, comment));
195-
}, []))));
235+
u('root', comments
236+
.map(function (comment) {
237+
if (options.markdownTables) {
238+
return unnest(comment);
239+
}
240+
return comment;
241+
})
242+
.reduce(function (memo, comment) {
243+
return memo.concat(generate(1, comment));
244+
}, []))));
196245
}
197246

198247
module.exports = commentsToAST;

‎lib/unnest.js

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
function unnestTag(comment, tag) {
2+
3+
if (comment[tag]) {
4+
var tagFlattened = [];
5+
comment[tag].forEach(flattenTag);
6+
comment[tag] = tagFlattened;
7+
8+
function flattenTag(tag) {
9+
tagFlattened.push(tag);
10+
if (tag.properties) {
11+
tag.properties.forEach(flattenTag);
12+
}
13+
tag.properties = undefined;
14+
}
15+
}
16+
17+
return comment;
18+
}
19+
20+
function unnest(comment) {
21+
return unnestTag(unnestTag(comment, 'params'), 'properties');
22+
}
23+
24+
module.exports = unnest;

0 commit comments

Comments
 (0)
0