人性化的文档生成器

我们希望有一个更人性化的文档自动生成器,可以把最大的精力放在书写文档本身,而不是其它的地方。然后就用FarBox的API做了一个;嘿,效果还真不错!
help.farbox.com & doc.farbox.com都是在此基础上实现的。

文档自动生成的效果(截图)

这是电脑本地上的一个文件夹结构

doc-os

这是根据文件夹自动生成的Web网站

doc-web

这是根据文件夹自动导出的PDF文件

Image Title

Image Title

如何使用这个文档自动生成器?

第一步,了解它运行的机制

FarBox可以将文件夹以及其包含的文件转为可查询的数据库结构,数据的查询可以通过模板API进行。FarBox上的日志,可以自己设定position字段,那么就能让所有的文档按照固定的次序排列。

简而言之,这个文档生成器,实际上就是FarBox的一个网站自定义模板而已。

第二步, 使用这个模板

FarBox中可以轻松的克隆一个模板,你只需要访问http://doc.farbox.com/template,然后填入自己的网站域名,就可以成功克隆这个文档生成器的模板了!

实际上,模板的源码也非常简洁,如果有必要,可以获取源码,自行修改,地址为https://github.com/BuildFarBox/doc.farbox.com

下载模板的ZIP包解压后,将template目录移到自己的网站目录下就可以了;如果之前已经克隆过doc.farbox.com上的模板了,则需要在自己的网站管理后台中,将模板引擎>模板优先级设置为自定义模板优先。

第三步,了解基本的使用规则

  1. 文档文件需要放在docs这个目录中,里面的index.md会是网站首页的内容;
  2. 左侧导航自动生成: docs的子目录(如果有文档)会作为二级导航存在,子目录内的则是具体的文档文件。
  3. 左侧导航中还有内嵌矛点的三级导航,这是当前文档声明了toc: yes而产生的。
  4. 目录与文件,其名字需要用类似1 name2 name进行命名,即数字+空格+名字的格式,数字即排序。

更多的使用规则,这都是由模板本身决定的;如果有必要,你可以自己修改模板。

隐藏特性!

自动生成PDF

你需要下载FarBox的桌面端程序FarEditor

运行FarEditor后,打开左侧的文件管理器,选择自己网站下的docs目录,点击右键,会有如下所示:
pack to pdf

然后按照操作提示进行下去即可,如果文档比较多,生成PDF的等待时间会比较长。

支持多国语言

默认的文档总目录为docs,如果另外还有docs-zh_cndocs-us_en这样的目录,那么访问网址时,增加?lang=zh_cn?lang=us_en就能匹配不同的文档总目录,而非原来的docs

默认情况下,则是根据访问者的国家,自动匹配的,比如国内的用户一般会先尝试去匹配docs-zh_cn这个总目录。

添加评论

只要进入自己网站的管理后台,添加Disqus或者多说的ID,就可以了。

这样,读者遇到不明白的问题,在当前文档内就能进行留言/评论, 这样的反馈可以帮助我们更好地完善文档!