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

Author: tmcw

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

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 || {}
     };
 

lib/commands/readme.js

@@ -42,6 +42,8 @@ module.exports.builder = {
   example: 'documentation readme index.js -s "API Docs" --github'
 };
 
+function noop() {}
+
 /**
  * Insert API documentation into a Markdown readme
  * @private
@@ -53,8 +55,7 @@ module.exports.handler = function readme(argv) {
   argv = sharedOptions.expandInputs(argv);
   argv.format = 'remark';
   /* eslint no-console: 0 */
-  var log = argv.q ? function () {}
-  : console.log.bind(console, '[documentation-readme] ');
+  var log = argv.q ? noop : console.log.bind(console, '[documentation-readme] ');
   var readmeFile = argv['readme-file'];
 
   build.handler(argv, onAst);

lib/output/markdown.js

@@ -1,7 +1,6 @@
 'use strict';
 
 var remark = require('remark'),
-  toc = require('remark-toc'),
   markdownAST = require('./markdown_ast');
 
 /**
@@ -26,9 +25,7 @@ var remark = require('remark'),
  * });
  */
 module.exports = function (comments, options, callback) {
-  var processor = remark().use(toc);
   markdownAST(comments, options, function (err, ast) {
-    var processedAST = processor.run(ast);
-    return callback(null, processor.stringify(processedAST));
+    return callback(null, remark().stringify(ast));
   });
 };

lib/output/markdown_ast.js

@@ -1,4 +1,6 @@
 var u = require('unist-builder'),
+  remark = require('remark'),
+  toc = require('remark-toc'),
   hljs = require('highlight.js'),
   GithubSlugger = require('github-slugger'),
   createLinkerStack = require('./util/linker_stack'),
@@ -14,7 +16,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 +35,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
@@ -202,10 +208,20 @@ function commentsToAST(comments, options, callback) {
     .filter(Boolean);
   }
 
-  return callback(null, rerouteLinks(linkerStack.link,
-    u('root', generatorComment.concat(comments.reduce(function (memo, comment) {
-      return memo.concat(generate(2, comment));
-    }, [])))));
+  var root = rerouteLinks(linkerStack.link,
+    u('root', generatorComment
+      .concat(options['no-markdown-toc'] ? [] : tableOfContentsHeading)
+      .concat(comments.reduce(function (memo, comment) {
+        return memo.concat(generate(2, comment));
+      }, []))));
+
+  if (!options['no-markdown-toc']) {
+    return remark().use(toc, {
+      tight: true
+    }).run(root, callback);
+  }
+
+  return callback(null, root);
 }
 
-module.exports = commentsToAST;
+module.exports = markdownAST;

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**

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**

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

@@ -5,6 +5,53 @@
       "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"
+        }
+      ],
+      "data": {
+        "id": "table-of-contents",
+        "htmlAttributes": {
+          "id": "table-of-contents"
+        },
+        "hProperties": {
+          "id": "table-of-contents"
+        }
+      }
+    },
+    {
+      "type": "list",
+      "ordered": false,
+      "children": [
+        {
+          "type": "listItem",
+          "loose": false,
+          "children": [
+            {
+              "type": "paragraph",
+              "children": [
+                {
+                  "type": "link",
+                  "title": null,
+                  "url": "#f",
+                  "children": [
+                    {
+                      "type": "text",
+                      "value": "f"
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
     {
       "depth": 2,
       "type": "heading",
@@ -13,7 +60,16 @@
           "type": "text",
           "value": "f"
         }
-      ]
+      ],
+      "data": {
+        "id": "f",
+        "htmlAttributes": {
+          "id": "f"
+        },
+        "hProperties": {
+          "id": "f"
+        }
+      }
     },
     {
       "type": "strong",

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.

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.