如何使用gitbook发布自己的书籍

Posted on | In , | Visitors:
Words : 1.2k | Reading ≈ 4 min

利用开源项目 gitbook，自己写本书吧～

前言：gitbook 平台在今年的4月9日发布了新的版本v2。新的版本官网已经变成 www.gitbook.com （旧的地址为 legacy.gitbook.com ）。新旧版本有很多的不一样，网上很多资料都是针对旧版。 比如新版不再支持把每本书作为一个 Git Repository 来进行版本管理。（以前是可以针对每本书从本地 git push 到 gitbook 的），这点也是坑了我很久（坑一个强迫症重度患者的结果就是，不扒出被坑的根本原因誓不罢休）。更多 v2 的重大改变可以看 这里。

以下的所有操作都是针对新版的 gitbook。

使用 gitbook 编写一本书的步骤如下：

基本用法

1. 全局安装 gitbook-cli

1
npm install gitbook-cli -g

2. 查看 gitbook 版本

1
gitbook --version

我在查看 gitbook 版本的时候，他会自动安装一些插件，等了一会安装完才出的版本信息：

1
2
CLI version: 2.3.2
GitBook version: 3.2.3

3. 初始化 gitbook

1
gitbook init

4. 编辑书籍

  • 一个 gitbook 项目至少要包含 README.md 和 SUMMARY.md，书本的第一页内容是从文件 README.md 文件中提取的。如果这个文件名没有出现在 SUMMARY.md 文件中，则它会被添加为章节的第一个条目。而由于一些托管在 github 上的书更喜欢将 README.md 作为项目的介绍而不是书的介绍，从 gitbook v2 起，可以在 book.json 中指定某个文件作为 README。例如：

    1
    2
    3
    4
    5
    {
    	"structure": {
    		"readme": "myIntro.md"
    	}
    }

  • gitbook 使用文件 SUMMARY.md 来定义书本的章节和子章节的结构。它用来生成书本内容的预览表。它的格式是一个简单的链接列表。另外可以在里面添加一些 markdown 格式的标题和分割线。例如：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    # 概要
    * [章节 1](chapter1.md)
    * [章节 2](chapter2.md)
    * [章节 3](chapter3.md)

    # 基础
    * [章节 1](chapter1/README.md)
      * [1.1 a](chapter1/a.md)
      * [1.2 b](chapter1/b.md)
    ---
    * [章节 2](chapter2/README.md)
      * [2.1 c](chapter2/c.md)
      * [2.2 d](chapter2/d.md)

    # 进阶
    * [章节 3](chapter3/README.md)

  • 编写文章内容
    接下来就可以在相应的 md 文件里书写内容了。

5. 启动 gitbook 本地服务

写完内容，可以通过以下方式来预览书本：

1
gitbook serve

gitbook serve 命令实际上是先调用 gitbook build 编译书籍，然后启动一个 web 服务器，监听在本地的4000端口。

gitbook 进阶

以上所说的都是在本地的操作，如何让别人也可以访问自己的书籍，除了自己买域名，还可以利用现有的互联网平台：gitbook.com、 github.com、 gitlab.com（gitlab也是听说可以有 gitlab pages，没有实际操作过，先略过）

1. 在 gitbook.com 上发布和管理书籍

  • 需要先注册 gitbook 账号。可以单独注册，也可以使用 github 账号关联登录。
  • 然后先创建一个 Orgnization 。
  • 再在这个 Orgnization 里面创建一个 Space（旧版叫 Book）。这个就是你的书籍项目了。
  • 然后就可以在线写书了～书籍的在线浏览地址为：https://yourorgnizationname.gitbook.io/yourspacename

2. 在 github.com 上发布和管理书籍

在前面说的本地操作，编辑和预览书籍后，可以把 build 之后的结果，上传到 github 上面，然后利用 github pages 来发布书籍。

  • 首先在 github 上新建一个跟你的书籍同名的 repository。
  • 然后将远程仓库地址添加到本地，然后将编译后的 _book 目录 push 到远程。
  • 然后在 github 上设置一下 github pages，具体方法和步骤我在另一个文章中详细介绍过：如何给github项目建立自己的主页。
  • 在设置完后，就可以通过 https://githubusername.github.io/projectname 来浏览你的书了。

3. gitbook 与 github 关联同步

新版 gitbook.com 不支持本地版本管理了，但是对 github 的集成支持的不错。可以通过配置，实现在 github 项目里面提交内容，gitbook 平台会自动同步过去。

  • 在 gitbook 平台里，进入要设置的 space，也就是你的书。
  • 点左下角的配置按钮，进入配置，点击 Intergrations ，找到 github。
  • 点击 link you github repository 按钮，根据向导，登录 github ，选择 reposirory，选择分支，完成绑定和同步。(你还可以选择是 gitbook 同步 github ，还是 github 同步 gitbook)

    需要注意的是：绑定的 github 仓库分支里面要是 gitbook 的源码，也就是那些 md 文件。而不是 build 之后生成的 html 文件。