feat(markdown): Add table of contents support for Markdown mode

Fixes #220
documentationjs · Dec 29, 2016 · 611ecbb · 611ecbb
1 parent 2ae5d8f
commit 611ecbb
Show file tree

Hide file tree

Showing 116 changed files with 1,029 additions and 6 deletions.
diff --git a/docs/NODE_API.md b/docs/NODE_API.md
@@ -1,5 +1,15 @@
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
+### Table of Contents
+
+-   [build](#build)
+-   [buildSync](#buildsync)
+-   [lint](#lint)
+-   [formats](#formats)
+-   [formats.html](#formatshtml)
+-   [formats.markdown](#formatsmarkdown)
+-   [formats.json](#formatsjson)
+
 ## build
 
 Generate JavaScript documentation as a list of parsed JSDoc

diff --git a/lib/commands/build.js b/lib/commands/build.js
@@ -26,6 +26,11 @@ module.exports.builder = extend({},
       default: 'json',
       choices: ['json', 'md', 'remark', 'html']
     },
+    'no-markdown-toc': {
+      describe: 'include a table of contents in markdown output',
+      default: 'stdout',
+      type: 'boolean'
+    },
     output: {
       describe: 'output location. omit for stdout, otherwise is a filename ' +
       '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) {
       version: argv['project-version'] || (argv.package || {}).version,
       theme: argv.theme,
       paths: argv.paths,
+      'no-markdown-toc': argv['no-markdown-toc'],
       hljs: argv.hljs || {}
     };
 

diff --git a/lib/output/markdown.js b/lib/output/markdown.js
@@ -26,7 +26,9 @@ var remark = require('remark'),
  * });
  */
 module.exports = function (comments, options, callback) {
-  var processor = remark().use(toc);
+  var processor = remark().use(toc, {
+    tight: true
+  });
   markdownAST(comments, options, function (err, ast) {
     var processedAST = processor.run(ast);
     return callback(null, processor.stringify(processedAST));

diff --git a/lib/output/markdown_ast.js b/lib/output/markdown_ast.js
@@ -14,7 +14,7 @@ var u = require('unist-builder'),
  * @param {Function} callback called with AST
  * @returns {undefined} calls callback
  */
-function commentsToAST(comments, options, callback) {
+function markdownAST(comments, options, callback) {
 
   // Configure code highlighting
   var hljsOptions = (options || {}).hljs || {},
@@ -33,6 +33,10 @@ function commentsToAST(comments, options, callback) {
     u('html', '<!-- Generated by documentation.js. Update this documentation by updating the source code. -->')
   ];
 
+  var tableOfContentsHeading = [
+    u('heading', { depth: 3 }, [u('text', 'Table of Contents')])
+  ];
+
   /**
    * Generate an AST chunk for a comment at a given depth: this is
    * split from the main function to handle hierarchially nested comments
@@ -203,9 +207,11 @@ function commentsToAST(comments, options, callback) {
   }
 
   return callback(null, rerouteLinks(linkerStack.link,
-    u('root', generatorComment.concat(comments.reduce(function (memo, comment) {
-      return memo.concat(generate(2, comment));
-    }, [])))));
+    u('root', generatorComment
+      .concat(options['no-markdown-toc'] ? [] : tableOfContentsHeading)
+      .concat(comments.reduce(function (memo, comment) {
+        return memo.concat(generate(2, comment));
+      }, [])))));
 }
 
-module.exports = commentsToAST;
+module.exports = markdownAST;
diff --git a/test/fixture/auto_lang_hljs/multilanguage.output.md b/test/fixture/auto_lang_hljs/multilanguage.output.md
@@ -1,5 +1,9 @@
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
+### Table of Contents
+
+-   [multilanguage.input](#multilanguageinput)
+
 ## multilanguage.input
 
 **Extends Foo, Bar**

diff --git a/test/fixture/boolean-literal-type.output.md b/test/fixture/boolean-literal-type.output.md
@@ -1,5 +1,9 @@
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
+### Table of Contents
+
+-   [f](#f)
+
 ## f
 
 **Parameters**

diff --git a/test/fixture/boolean-literal-type.output.md.json b/test/fixture/boolean-literal-type.output.md.json
@@ -5,6 +5,16 @@
       "type": "html",
       "value": "<!-- Generated by documentation.js. Update this documentation by updating the source code. -->"
     },
+    {
+      "depth": 3,
+      "type": "heading",
+      "children": [
+        {
+          "type": "text",
+          "value": "Table of Contents"
+        }
+      ]
+    },
     {
       "depth": 2,
       "type": "heading",

diff --git a/test/fixture/class.config.output.md b/test/fixture/class.config.output.md
@@ -1,5 +1,12 @@
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
+### Table of Contents
+
+-   [MyClass](#myclass)
+    -   [getFoo](#getfoo)
+    -   [getUndefined](#getundefined)
+-   [Hello](#hello)
+
 ## MyClass
 
 This is my class, a demo thing.

diff --git a/test/fixture/class.output.md b/test/fixture/class.output.md
@@ -1,5 +1,11 @@
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
+### Table of Contents
+
+-   [MyClass](#myclass)
+    -   [getFoo](#getfoo)
+    -   [getUndefined](#getundefined)
+
 ## MyClass
 
 This is my class, a demo thing.

diff --git a/test/fixture/class.output.md.json b/test/fixture/class.output.md.json
@@ -5,6 +5,16 @@
       "type": "html",
       "value": "<!-- Generated by documentation.js. Update this documentation by updating the source code. -->"
     },
+    {
+      "depth": 3,
+      "type": "heading",
+      "children": [
+        {
+          "type": "text",
+          "value": "Table of Contents"
+        }
+      ]
+    },
     {
       "depth": 2,
       "type": "heading",

diff --git a/test/fixture/document-exported-export-default-object.output.md b/test/fixture/document-exported-export-default-object.output.md
@@ -1,5 +1,10 @@
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
+### Table of Contents
+
+-   [document-exported-export-default-object.input](#document-exported-export-default-objectinput)
+-   [x](#x)
+
 ## document-exported-export-default-object.input
 
 ## x
diff --git a/test/fixture/document-exported-export-default-object.output.md.json b/test/fixture/document-exported-export-default-object.output.md.json
@@ -5,6 +5,16 @@
       "type": "html",
       "value": "<!-- Generated by documentation.js. Update this documentation by updating the source code. -->"
     },
+    {
+      "depth": 3,
+      "type": "heading",
+      "children": [
+        {
+          "type": "text",
+          "value": "Table of Contents"
+        }
+      ]
+    },
     {
       "depth": 2,
       "type": "heading",

diff --git a/test/fixture/document-exported-export-default-value.output.md b/test/fixture/document-exported-export-default-value.output.md
@@ -1,3 +1,7 @@
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
+### Table of Contents
+
+-   [document-exported-export-default-value.input](#document-exported-export-default-valueinput)
+
 ## document-exported-export-default-value.input
diff --git a/test/fixture/document-exported-export-default-value.output.md.json b/test/fixture/document-exported-export-default-value.output.md.json
@@ -5,6 +5,16 @@
       "type": "html",
       "value": "<!-- Generated by documentation.js. Update this documentation by updating the source code. -->"
     },
+    {
+      "depth": 3,
+      "type": "heading",
+      "children": [
+        {
+          "type": "text",
+          "value": "Table of Contents"
+        }
+      ]
+    },
     {
       "depth": 2,
       "type": "heading",

diff --git a/test/fixture/document-exported.output.md b/test/fixture/document-exported.output.md
@@ -1,5 +1,38 @@
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
+### Table of Contents
+
+-   [z](#z)
+    -   [zMethod](#zmethod)
+-   [x](#x)
+-   [Class](#class)
+    -   [classMethod](#classmethod)
+    -   [classGetter](#classgetter)
+    -   [classSetter](#classsetter)
+    -   [staticMethod](#staticmethod)
+    -   [staticGetter](#staticgetter)
+    -   [staticSetter](#staticsetter)
+-   [T5](#t5)
+-   [y2Default](#y2default)
+-   [y4](#y4)
+-   [object](#object)
+    -   [prop](#prop)
+    -   [func](#func)
+-   [method](#method)
+-   [getter](#getter)
+-   [setter](#setter)
+-   [f1](#f1)
+-   [f3](#f3)
+-   [T](#t)
+-   [T2](#t2)
+-   [T4](#t4)
+-   [f4](#f4)
+-   [o1](#o1)
+-   [om1](#om1)
+-   [f5](#f5)
+-   [o2](#o2)
+-   [om2](#om2)
+
 ## z
 
 ### zMethod

diff --git a/test/fixture/document-exported.output.md.json b/test/fixture/document-exported.output.md.json
@@ -5,6 +5,16 @@
       "type": "html",
       "value": "<!-- Generated by documentation.js. Update this documentation by updating the source code. -->"
     },
+    {
+      "depth": 3,
+      "type": "heading",
+      "children": [
+        {
+          "type": "text",
+          "value": "Table of Contents"
+        }
+      ]
+    },
     {
       "depth": 2,
       "type": "heading",

diff --git a/test/fixture/es6-class.output.md b/test/fixture/es6-class.output.md
@@ -1,5 +1,12 @@
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
+### Table of Contents
+
+-   [Foo](#foo)
+-   [Bar](#bar)
+    -   [constructor](#constructor)
+    -   [bar](#bar-1)
+
 ## Foo
 
 **Extends React.Component**

diff --git a/test/fixture/es6-class.output.md.json b/test/fixture/es6-class.output.md.json
@@ -5,6 +5,16 @@
       "type": "html",
       "value": "<!-- Generated by documentation.js. Update this documentation by updating the source code. -->"
     },
+    {
+      "depth": 3,
+      "type": "heading",
+      "children": [
+        {
+          "type": "text",
+          "value": "Table of Contents"
+        }
+      ]
+    },
     {
       "depth": 2,
       "type": "heading",

diff --git a/test/fixture/es6-default2.output.md b/test/fixture/es6-default2.output.md
@@ -1,5 +1,9 @@
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
+### Table of Contents
+
+-   [es6-default2.input](#es6-default2input)
+
 ## es6-default2.input
 
 **Parameters**

diff --git a/test/fixture/es6-default2.output.md.json b/test/fixture/es6-default2.output.md.json
@@ -5,6 +5,16 @@
       "type": "html",
       "value": "<!-- Generated by documentation.js. Update this documentation by updating the source code. -->"
     },
+    {
+      "depth": 3,
+      "type": "heading",
+      "children": [
+        {
+          "type": "text",
+          "value": "Table of Contents"
+        }
+      ]
+    },
     {
       "depth": 2,
       "type": "heading",

diff --git a/test/fixture/es6-import.output.md b/test/fixture/es6-import.output.md
@@ -1,5 +1,11 @@
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
+### Table of Contents
+
+-   [multiplyTwice](#multiplytwice)
+-   [es6-ext](#es6-ext)
+-   [simple.input](#simpleinput)
+
 ## multiplyTwice
 
 This function returns the number one.

diff --git a/test/fixture/es6-import.output.md.json b/test/fixture/es6-import.output.md.json
@@ -5,6 +5,16 @@
       "type": "html",
       "value": "<!-- Generated by documentation.js. Update this documentation by updating the source code. -->"
     },
+    {
+      "depth": 3,
+      "type": "heading",
+      "children": [
+        {
+          "type": "text",
+          "value": "Table of Contents"
+        }
+      ]
+    },
     {
       "depth": 2,
       "type": "heading",