Gitbook快速简明教程
Gitbook是一款Markdown编辑器,也是一个在线的内容写作网站。使用Gitbook编辑器(也可以是别的Markdown编辑器)编写的内容,可以同步备份到 gitbook.com 官网、github仓库、或其他任何git服务器。因为内容是Markdown格式,所以编写简单,支持版本管理,非常适合用于制作用户手册、开发文档或者API说明文档等技术资料。
以下说明如何在Windows系统中安装Gitbook,以及编写一个简单的文档,再同步到github.com,最后说明如何生成PDF、HTML等格式文件。
1 安装编辑器
Gitbook编辑器下载地址:https://www.gitbook.com/editor/。
下载之后安装,安装过程和其他软件一样。
2 使用编辑器
因为我们的代码要同步到自己的github仓库,所以不需要注册gitbook账号。
创建文档
打开GitBook Editor,选择菜单“File”>“New Book”,输入Book的名字,如“dev-book”,再点“Create Book”按钮创建书籍。
然后就可以编辑文件了。
GitBook编辑器创建的书籍默认保存在用户目录下,比如我的是:C:\Users\Gary\GitBook\Library\Import,其中Gary是我的用户名。
如果是已经创建的文档,也可以通过菜单“File”>“Open…”也开已存在的书籍。
界面
编辑器的界面说明如下:
切换到编辑模式后,用Markdown语法编写文档,Markdown语法可参考:http://www.jianshu.com/p/q81RER。
设置git仓库
菜单选择“Book”>“Repository Settings…”,在输入框中输入仓库地址。注意,gitbook编辑器目前只支持https格式的地址。例如:https://github.com/yeszao/fastphp.git。
编辑器配置
编辑器的配置文档是book.json,在书籍的目录根目录下,选择菜单“Book”>“Edit Configuration”在编辑器中打开配置文件。输入如下内容:
{ "title": "开发文档" }
book.json文件用于配置生成PDF、HTML的标题、样式,以及插件插件的使用。
Gitbook书籍下的*.md文件和book.json文件请直接用Gitbook编辑器编辑,如果用别的编辑器编辑文件,请在编辑后保存并用git提交,否则这些文件的内容会被Gitbook编辑器中的内容覆盖。
这些步骤完成后,在书籍目录下生成如下的文件结构。
这个目录已经包含了:
- .git文件
- git忽略文件
- book.json书籍配置文件
- chapter1.md示例章节文件
- README.md全局说明文件
- SUMMARY.md目录结构文件
3 生成HTML文件
要生成HTML文件,必须要通过nodejs来安装gitbook-cli和gitbook。步骤如下。
安装nodejs
到nodejs网站下载最新版本的nodejs windows版本,地址:https://nodejs.org/en/download/。
下载完成后双击安装,安装完成后在DOS命令下就可以用node和npm命令了,通过下面命令可以查看版本号。
> node -v > npm -v
安装gitbook
在DOS下使用下面的命令安装:
npm install gitbook-cli -g
在通过下面的命令检查是否安装成功,并同时安装gitbook,
gitbook -V
生成HTML文件
在DOS中切换到书籍目录C:\Users\Gary\GitBook\Library\Import\dev-book,输入下面的命令即可生成HTML文件,
gitbook build
生成的文件会在书籍目录_book下,把这些HTML文件放到网站服务器上,就是一个内容网站了。
4 插件推荐
目录折叠
toggle-chapters 插件的效果是:默认只在目录导航中显示章的标题,而不会显示小节的标题,点击每一章或者每一节会显示当前章或节的子目录,如果有的话,但是同时会收起其它之前展开的章节。所以,个人认为不是非常实用,因为这样子用户不能快速跳转到没有展开的章节!
安装和使用非常简单,参考官方文档即可!
npm install gitbook-plugin-toggle-chapters
修改book.json,内容:
{ "plugins": ["toggle-chapters"] }
这样就完成了。
参考资料: