gitbook使用教程

头像
dragon
    阅读 9 分钟
    18

    1. 说明

    gitbook网站是一个简单的个人在线书籍网站，在这里可以把自己的文档整理成书籍发布出来，便于阅读。
    gitbook网站：https://legacy.gitbook.com/

    本文主要讲解在gitbook网站上发布一个书籍文档和使用gitbook提供的工具在本地开发一个书籍文档部署到自己的服务上

    在此之前你需要会如下准备：

    • 账号： github有账号，gitbook使用github账号注册
    • git：代码管理工具
    • Markdown：gitbook主要使用MD语法来编写书籍的
    • gitbook工具：如果你在本地开发需要安装此插件，下面有介绍
    • nodejs环境：gitbook插件需要的运行环境
    • 一款Markdown编辑器：方便本地开发，推荐Typora或gitbook自己的编辑器gitbook editor

    2. 在gitbook网站上创建一本文档书籍

    此种方式是使用github网站加gitbook网站的方式来创建书籍的。
    首先你要有一个github账号，然后在github网站中创建了一个repo仓库，用于存放书籍内容的仓库。
    注意：gitbook网站有时需要使用代理才能打开。

    2.1 登陆gitbook网站

    gitbook网站支持直接使用github账号登陆的，推荐直接使用github账号登陆。
    打开gitbook网站：https://legacy.gitbook.com/
    点击右上角的Sign In登陆，然后选择Sign in with GitHub选择使用github账号进行登陆。
    第一次登陆gitbook网站时，需要github网站的认证，还需要到注册github网站的邮箱中点击确认。
    clipboard.png

    2.2 创建一本书

    2.2.1 点击新建一本书按钮

    登陆网站后，点击右上角的用户图标，然后选择Your Profile。然后就会在右上角看见+ new按钮，点击此按钮就是创建一本书。
    clipboard.png
    或者在gitbook的dashboard页面有一个New Book按钮，点击也可以创建一个书籍：
    clipboard.png
    或者打开此链接，直接进入创建书籍页面：https://legacy.gitbook.com/new

    2.2.2 在创建书籍中选择github

    进入新建页面后，在左边找到GITHUB选项。
    第一次需要点击右边的install github integration。
    此时会跳转到github页面去安装这个插件，可以选择所有仓库或者某个仓库，然后点击install安装,输入github密码后完成安装。
    此时回到gitbook新建页面刷新，选择github后，会在右边会出现如下选项：

    • title ： 书籍的标题
    • description：对这本书的描述
    • Select a Repository: 选择github中的仓库等
    • Public or Private: 这本书是公开(Public)还是私有(Private)的

    选项填好后，然后点击create book按钮。
    clipboard.png

    注意：标题一定要是英文的，因为这要作为这本书籍的链接（创建成功后可修改名称）。

    点击create book按钮后，会出现这本书籍页面，然后刷新页面，然后点击ABOUT。
    clipboard.png

    然后点击右边的Read按钮即可阅读。
    clipboard.png

    进入阅读后如下效果：
    clipboard.png

    此时一本书籍已经在gitbook上创建完毕了。

    2.3 创建书籍目录文件

    经过上面的步骤后，只是创建了一本书籍，但是此时还不完整，因为缺少了书籍的目录。
    首先需要在项目的根目录创建一个SUMMARY.md文件，此文件就是gitbook的目录，内容格式如下：

    * [说明](README.md)
* HTML
  - [测试连接1](/doc/a.md) 
* JAVASCRIPT
  - [b文件](/javascript/b.md)

    此时项目目录结构：

    .
├── README.md
├── SUMMARY.md
├── doc
│   └── a.md
└── javascript
    └── b.md

    保存SUMMARY.md后，提交内容到github网站仓库中，需要等待一会才能在gitbook网站上看见更新内容，有时需要等很久才能更新，最终效果如下图所示：

    clipboard.png

    3. 使用gitbook工具开发

    上面说的在gitbook网站发布一本书虽然方便，但是有如下缺点：

    1、gitbook网站经常打不开，需要使用代理才能访问
    2、修改提交后有时需要很久才能显示更新

    还好，gitbook还提供了基于Node.js的命令行工具，可使用 Github/Git 和 Markdown 来制作精美的电子书,然后部署到自己的网站上(或在github托管)。

    gitbook命令行工具首先需要本地电脑有nodejs和终端。
    一般linux系统和Mac系统自带nodejs和终端，Windows系统需要安装nodejs和终端。
    windows系统推荐cmder终端,安装和介绍请自行查找。
    可使用如下命令在终端查看系统是否有nodejs：

    node -v
v8.12.0

    如果出现版本号，那么说明已经安装了，如果没找到这个命令，那么进入node官网：http://nodejs.cn/ ，选择下载，选择对应的操作系统后下载安装即可。

    gitbook命令行工具推荐nodejs版本要v4.0.0以上，如果版本过低，可看如下教程将版本升级到v4.0.0以上：
    https://segmentfault.com/a/11...

    3.1 安装gitbook-cli工具

    gitbook-cli是一个在同一系统上安装和使用多个版本的GitBook的实用程序。它将自动安装所需版本的GitBook来构建一本书。
    打开终端输入npm install gitbook-cli -g命令进行全局安装：

    npm install gitbook-cli -g

npm http fetch GET 304 https://registry.npm.taobao.org/os-tmpdir 100ms (from cache)
npm http fetch GET 304 https://registry.npm.taobao.org/os-homedir 113ms (from cache)
/usr/local/bin/gitbook -> /usr/local/lib/node_modules/gitbook-cli/bin/gitbook.js
+ gitbook-cli@2.3.2
added 578 packages from 672 contributors in 17.806s

    clipboard.png
    安装成功后可使用gitbook --version来查看是否安装成功：

    gitbook --version
CLI version: 2.3.2
GitBook version: 3.2.3

    注意：终端第一次运行gitbook命令，可能会自动安装gitbook，因为刚才安装的是CLI，此时CLI会自动安装gitbook。

    如果想卸载CLI，可使用npm uninstall gitbook-cli -g来删除。

    3.2 初始化一本书

    初始化一本书的命令是gitbook init,

    首先在终端创建一个项目目录，并进入这个目录：

    mkdir book
cd book

    然后使用gitbook init来初始化一本书：

    ~ gitbook init

warn: no summary file in this book 
info: create README.md 
info: create SUMMARY.md 
info: initialization is finished

    gitbook init会在空项目中创建README.md和SUMMARY.md两个文件：
    README.md文件是项目的介绍文件。
    SUMMARY.md是gitbook书籍的目录。
    clipboard.png

    如果SUMMARY.md文件里面有如下内容：

    * [项目介绍](README.md)
* http
    * [http说明](doc/http/http解析.md)
        * [tcp说明](doc/http/tcp/tcp说明.md)
            * [udp说明](doc/http/tcp/udp/udp说明.md)
* HTML
    * [HTML5-特性说明](doc/html/HTML5-特性说明.md)

    那么在使用gitbook init时，如果目录里面的文件不存在，则会创建目录中的文件：

    ~ gitbook init

info: create doc/http/http解析.md 
info: create doc/http/tcp/tcp说明.md 
info: create doc/http/tcp/udp/udp说明.md 
info: create doc/html/HTML5-特性说明.md 
info: create SUMMARY.md 
info: initialization is finished

    clipboard.png

    3.3 本地启动服务编写书籍

    终端打开项目目录，使用gitbook serve启动服务：

    ~ gitbook serve

Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed 
info: loading plugin "livereload"... OK 
……
info: loading plugin "theme-default"... OK 
info: found 5 pages 
info: found 0 asset files 
info: >> generation finished with success in 2.1s ! 

Starting server ...
Serving book on http://localhost:4000

    然后根据终端的提示，在浏览器中打开http://localhost:4000查看书籍，效果如下图所示：
    clipboard.png
    注意：gitbook serve命令会在项目中生成一个_book的文件夹,此文件夹就是最终生成的项目。

    3.4 文档打包

    可使用gitbook build命令来生成最终的项目：

    ~ gitbook build

info: 7 plugins are installed 
info: 6 explicitly listed 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 5 pages 
info: found 0 asset files 
info: >> generation finished with success in 1.0s !

    命令执行结束后，会在项目下生成_book的文件夹,此文件夹就是最终生成的项目。
    在_book文件夹里有一个index.html文件，这个文件就是文档网站的HTM入口，把_book文件夹复制到服务器，然后把web服务的入口引向index.html即可完成文档网站的部署。

    如果你想查看输出目录详细的记录，可使用gitbook build ./ --log=debug --debug来构建查看。

    3.5 生成电子书

    这里本人试了，没有成功，你可以尝试一下

    GitBook 可以生成一个网站，但也可以输出内容作为电子书（ePub，Mobi，PDF）。

    # Generate a PDF file
$ gitbook pdf ./ ./mybook.pdf

# Generate an ePub file
$ gitbook epub ./ ./mybook.epub

# Generate a Mobi file
$ gitbook mobi ./ ./mybook.mobi

    我还在网上找了一个包：https://www.npmjs.com/package... ，可以试一下

    3.6 项目部署到GitHub Pages

    这部分需要使用git和github网站，如果你不会，请自行在网上搜索文档查看。

    由于gitbook生成的项目跟文档的源码是两个部分，所以可以把文档放到master分支上，部署的网站放到gh-pages 分支。

    3.6.1 在github上创建一个仓库

    这个仓库用于存放你编写的项目，和部署项目，如何创建请自行查找。

    3.6.2 本地项目提交到github仓库

    在项目中创建一个.gitignore文件，内容如下：

    # 忽略gitbook生成的项目目录
_book

    然后终端打开项目，输入如下命令,来提交文档项目到github上：

    ~ git init
~ git add .
~ git commit -m '初始化gitbook本地项目'
~ git remote add origin https://github.com/yulilong/book.git 
~ git push -u origin master

    上面命令执行结束后，就会把代码提交到github上的仓库。
    注意仓库地址要替换成你自己的链接。

    3.6.3 生成项目并上传到github仓库的gh-pages分支

    由于打包命令太多，为了简单化，现在写一个脚本命令来自动执行。当然你也可以终端自己执行这些命令。

    为了部署方便，可以创建一个脚本文件deploy.sh,内容如下：

    #!/usr/bin/env sh

echo '开始执行命令'
# 生成静态文件
echo '执行命令：gitbook build .'
gitbook build .

# 进入生成的文件夹
echo "执行命令：cd ./_book\n"
cd ./_book

# 初始化一个仓库，仅仅是做了一个初始化的操作，项目里的文件还没有被跟踪
echo "执行命令：git init\n"
git init

# 保存所有的修改
echo "执行命令：git add -A"
git add -A

# 把修改的文件提交
echo "执行命令：commit -m 'deploy'"
git commit -m 'deploy'

# 如果发布到 https://<USERNAME>.github.io/<REPO>
echo "执行命令：git push -f https://github.com/yulilong/book.git master:gh-pages"
git push -f https://github.com/yulilong/book.git master:gh-pages

# 返回到上一次的工作目录
echo "回到刚才工作目录"
cd -

    注意脚本文件代码中仓库地址要替换成你自己的地址。

    文件保存后，在终端执行如下命令，把生成的项目推送到github仓库上的gh-pages分支：

    bash deploy.sh

    执行成功后，打开你的github仓库，然后选择branch分支，会发现多了一个gh-pages分支，打开这个分之后，里面会有一个index.html文件。说明部署的代码上传成功了。
    注意：如果没有gh-pages分支说明没有部署成功请查看刚才执行的终端看哪里报错了，解决报错直到成功部署。

    3.6.4 配置GitHub Pages显示网站

    在github网站上的仓库里面点击Settings -> GitHub Pages选项中 -> Source里面选择gh-pages branch 然后点击Save按钮，然后在GitHub Pages下面就会看见一个网址，这个网址就是最终的网站。
    最终效果如下图所示：
    clipboard.png

    3.7 一些部署到GitHub Pages的例子

    https://github.com/yodaos-pro...

    http://gitbook.zhangjikai.com...

    4. gitbook的配置文件讲解

    如果你想对你的网站有更详细的个性化配置或使用插件，那么需要使用配置文件。
    配置文件写完后，需要重启服务或者重新打包才能应用配置。
    gitbook的配置文件名是book.json，首先在项目的根目录中创建book.json文件。
    book.json主要内容：

    {
    "title": "我的一本书",
    "author" : "yu",
    "description" : "我第一本书的描述，很好",
    "language" : "zh-hans",
    "structure": {
        "readme": "introduction.md"
    },
    "plugins": [
        "-lunr",
        "-search",
        "search-pro",
        "back-to-top-button"
    ],
    "pluginsConfig": {
        "anchor-navigation-ex": {
            "isShowTocTitleIcon": true
        }
    },
    "links" : {
        "sidebar" : {
            "个性链接1" : "https://www.baidu.com",
            "个性链接2" : "https://www.baidu.com"
        }
    },
    "styles": {
        "website": "styles/website.css",
        "ebook": "styles/ebook.css",
        "pdf": "styles/pdf.css",
        "mobi": "styles/mobi.css",
        "epub": "styles/epub.css"
    }
}

    更多的配置参数：https://github.com/GitbookIO/...

    4.1 book.json中一些主要参数说明

    • title
      标题
    • author
      作者
    • description
      描述，对应gitbook网站的description
    • language
      使用的语言，zh-hans是简体中文，会对应到页面的<html lang="zh-hans" >

    • structure
      指定 Readme、Summary、Glossary 和 Languages 对应的文件名，下面是这几个文件对应变量以及默认值：

      Variable Description
      structure.readme Readme file name (defaults to README.md)
      structure.summary Summary file name (defaults to SUMMARY.md)
      structure.glossary Glossary file name (defaults to GLOSSARY.md)
      structure.languages Languages file name (defaults to LANGS.md)

      比如想把readme文件个名字，则可以使用如下配置

      "structure": {
    "readme": "introduction.md"
},

      使用这个配置后，gitbook服务就不会找readme文件，而去找introduction文件当项目说明，这样就可以把readme文件完全当成代码仓库说明文档了。

    • plugins
      使用的插件列表，所有的插件都在这里写出来，然后使用gitbook install来安装。
    • pluginsConfig
      插件的配置信息，如果插件需要配置参数，那么在这里填写。

    • links
      目前可以给侧导航栏添加链接信息

      "links" : {
    "sidebar" : {
        "个性链接1" : "https://www.baidu.com"
    }
}

    • styles
      自定义页面样式，各种格式对应各自的css文件

      "styles": {
    "website": "styles/website.css",
    "ebook": "styles/ebook.css",
    "pdf": "styles/pdf.css",
    "mobi": "styles/mobi.css",
    "epub": "styles/epub.css"
}

    4.1 配置默认主题

    默认的主题可以通过配置来做一下效果。
    比如侧边栏菜单显示标题数字，可以在配置文件的pluginsConfig参数中写入如下字段：

    {
    "pluginsConfig": {
        "theme-default": {
            "showLevel": true
        }
    }
}

    效果如下图：

    clipboard.png

    5. gitbook的一些实用插件

    gitbook插件可以解决一些网站不太方便的地方，如侧边栏导航不能收缩，自带搜索不支持中文等。
    用了插件书籍网站会更灵活和美观。

    由于插件很多，请参考我的另一篇文章：https://segmentfault.com/a/11...

    参考资料

    gitbook 的配置文件book.json说明
    gitbook工具文档
    GitBook Editor
    gitbook 评论插件
    Gitbook 使用教程
    gitbook 实用插件

    Microsoftgitbookgithub
    dragon
    808 声望28 粉丝

    一个前端页面开发者，用过react、vue前端框架

    « 上一篇
    JavaScript运行机制和事件循环
    下一篇 »
    Gitalk评论插件使用教程

    引用和评论

    被 1 篇内容引用
    推荐阅读
    头像
    让vuepress支持图片放大功能

    dragon阅读 5.3k评论 2

    头像
    精简实用！一分钟搭建文件管理服务！

    Java陈序员赞 1阅读 615

    头像
    ABAP git客户端

    注销阅读 2.9k

    头像
    写在Github被微软收购之际 - Github的那些另类用法

    注销赞 2阅读 1.9k

    头像
    使用代码将github仓库里某个issue同步到CSDN博客上

    注销阅读 2.2k

    头像
    开发一个简单的工具，导出github仓库所有issue列表

    注销阅读 2.2k

    头像
    一个简单的例子学会github repository的webhook

    注销阅读 1.6k

    0 条评论
    得票最新