Gitbook快速简明教程

4.9k 记录 发表评论

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…”也开已存在的书籍。

界面

编辑器的界面说明如下:

editor

切换到编辑模式后,用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-book-dir

这个目录已经包含了:

  1. .git文件
  2. git忽略文件
  3. book.json书籍配置文件
  4. chapter1.md示例章节文件
  5. README.md全局说明文件
  6. SUMMARY.md目录结构文件

3 生成HTML文件

要生成HTML文件,必须要通过nodejs来安装gitbook-cligitbook。步骤如下。

安装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"]
}

这样就完成了。

 

参考资料:

  1. GitBook 简明教程
  2. 我的GitBook笔记
  3. 献给写作者的 Markdown 新手指南

发表回复

您的电子邮箱地址不会被公开。 必填项已用 * 标注

昵称 *