为JSDoc3文档增加导航菜单

默认生成的JSDoc3文档只有类和方法的导航。我前面文档提到如何为index.html增加内容描述。

但当我们从导航菜单切换到具体某个类的doc时，再想切换会index首页，默认生成doc中没有这样的能力。

其实JSDoc3现在的版本（3.2.2）确实没有这个功能，但我们可以通过JSDoc3提供的Tutorials功能，折中实现这个功能。

JSDoc3的Tutorials本意是，让使用者提供的文档除了API的doc之外，还可以提供其它的描述文档，比如总体介绍，背景说明，示例文档等等。

我还是以之前文章的搭配为例，JSDoc3+Docstrap。

假设我的js文件位于：d:\myjs\，要生成的jsdoc放在d:\mydoc。在《为JSDoc3的index.html增加说明文档》中，我使用markdown格式创建了一个README.md文件，这里我们可以继续使用到这个文件。

在任意位置创建一个文件夹，假设d:\myjs\Tutorials，文件夹名称也是任意的。把README.md复制到Tutorials文件夹中。

执行dos命令：

jsdoc d:\myjs d:\myjs\README.md -t d:\docstrap\template -c d:\docstrap\jsdoc.conf.json -d d:\docstrap_doc -u d:\myjs\Tutorials

命令执行完毕，我们再打开index.html，会发现上方导航菜单中增加了一项“Tutorials”，点开可以看到里面有一个菜单项“README”。点击README后显示的页面跟index.html还是挺像的，只是没有右侧的纵向导航菜单。但这个基本可以满足用户的需求了。

其实Tutorials目录中放入的所有扩展名为xml，xhtml，html，htm的文件，以及扩展名为md，markdown的文件都会被自动添加到Tutorials菜单中，这样就方便我们写出很多其它文档了。

继续上面的例子，导航菜单中显示的是“README”字样，这样总觉得有点别扭，这是因为JSDoc3默认就是使用文件名作为菜单项。而JSDoc3是支持我们修改菜单标题的。

在上面例子中的Tutorials目录中增加一个README.json文件，在文件中增加内容：

{
"title" : "首页"
}

再重新执行生成命令，我们可以看到“Tutorials”菜单中原来的“README”已经变更为“首页”字样。

我们还可以将Tutorials目录中的文件组织成上下级菜单的形式。下面的例子不是很严谨，大家理解就行。

比如在Tutorials目录中还有a.html，b.html，我们想让a.html，b.html成为“首页”的子菜单。

则修改README.json文件如下：

{
"title" : "首页",
"children" : ["a","b"]
}

再重新执行生成命令，点击Tutorials菜单中的“首页”，在显示的页面中，会看到上面增加了两个链接，a和b。点击a和b，会分别显示a.html和b.html。

理论上，按照同样的方法，a和b也可以继续扩展子菜单，我没有继续尝试。感兴趣的可以自己试试。

 

另外，看到官方的几个讨论，应该是支持将所有的json配置放在一个文件中的，有兴趣的也可以试试。

讨论：

https://github.com/jsdoc3/jsdoc/issues/332

https://github.com/jsdoc3/jsdoc/pull/334

https://github.com/jsdoc3/jsdoc3.github.com/pull/18