生成Markdown编写的API文档为HTML并加入Toc

需求

最近在编写API文档,有如下需求:

  • 使用 Markdown编写

  • 生成HTML并要根据 H1、H2… 标记生成Toc目录

解决方案

最终找到了开源项目 i5ting_ztree_toc ,它是一个jQuery插件,可以根据h1到h6自动生成toc,并且可以自动编号。并且作者还写了个工具,支持 Markdown 转 html ,并带有toc功能。

安装

gem install tocmd

用法

指定单个文件

tocmd -f shiti.md

指定目录

tocmd -d .

问题

如上就可以生成一个漂亮的带有 Toc 的 Html 页面了,但是尿点来了,它具有如下问题:

  1. 无法转换 Markdown 的表格代码
  2. 生成的 Html 包含了用到的 jQuery、Css 资源,但是它全部都在 gem 包安装路径,如果你想把这个 Html 页面发给其他人观看,那么你就要 Copy 资源文件一起发给他。
  3. 貌似是个别问题,生成 Html 以后,如果 Toc 的高度大于浏览器的高度,就没有办法滚动,解决方法就是给 Toc 加一个 Height

以上问题已经Email给作者,并且得到他的回复,并且承诺第一个问题会即时解决

替代方法

可以把 i5ting_ztree_toc 项目里需要用的文件下载到本地,然后自行添加,并且需要使用其他工具生成 Html 文档。

我目前就使用了如上方法,生成 Html 的软件是 Mou,并且生成的 Html 会解析 Markdown 的 Table 标签。

并且编写文档的时候使用如下方式:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
<ul id="tree" class="ztree"></ul>
<script type="text/javascript" src="http://wp.simman.cc/Public/file_dldq_org/jquery-1.10.2.min.js"></script>
<script type="text/javascript" src="http://wp.simman.cc/Public/file_dldq_org/jquery.ztree.all-3.5.min.js"></script>
<script type="text/javascript" src="http://wp.simman.cc/Public/file_dldq_org/jquery.ztree_toc.js"></script>
<SCRIPT type="text/javascript" >
<!--
var winWidth = 0;
var winHeight = 0;
function findDimensions() //函数:获取尺寸
{

//获取窗口宽度
if (window.innerWidth)
winWidth = window.innerWidth;
else if ((document.body) && (document.body.clientWidth))
winWidth = document.body.clientWidth;
//获取窗口高度
if (window.innerHeight)
winHeight = window.innerHeight;
else if ((document.body) && (document.body.clientHeight))
winHeight = document.body.clientHeight;
//通过深入Document内部对body进行检测,获取窗口大小
if (document.documentElement && document.documentElement.clientHeight && document.documentElement.clientWidth)
{
winHeight = document.documentElement.clientHeight;
winWidth = document.documentElement.clientWidth;
}
}

findDimensions();

$(document).ready(function(){
$('#tree').ztree_toc({
is_auto_number:true,
documment_selector:'.markdown-body',
ztreeStyle: {
width:'260px',
height: winHeight,
overflow: 'auto',
position: 'fixed',
'z-index': 2147483647,
border: '0px none',
left: '0px',
top: '0px' ,
}
});
});
//-->
</SCRIPT>


<article class='markdown-body' style="width:85%; margin-left:25%;border: 1px solid #CACACA; padding: 30px; border-radius:3px;" >

<!-- 这里直接书写 Markdown 代码 -->

</article>

<link href="http://wp.simman.cc/Public/file_dldq_org/github-bf51422f4bb36427d391e4b75a1daa083c2d840e.css" media="all" rel="stylesheet" type="text/css"/>
<link href="http://wp.simman.cc/Public/file_dldq_org/github2-d731afd4f624c99a4b19ad69f3083cd6d02b81d5.css" media="all" rel="stylesheet" type="text/css"/>
<link href="http://wp.simman.cc/Public/file_dldq_org/zTreeStyle.css" media="all" rel="stylesheet" type="text/css"/>

上面的资源文件大家需要下载到本地,因为我已经做了防盗链功能,流量有限,对不住大家了

上面的方法其实是参考其他以为博主的,我加入了使用简单的处理,不过遗憾的是实在找不到原来的链接,找到后会马上更新