网站内容更新中(gitbook网站发布一个书籍文档和使用gitbook提供的工具(图))

　　网站内容更新中(gitbook网站发布一个书籍文档和使用gitbook提供的工具(图))

　　1. 说明

　　gitbook网站是一个简单的个人在线图书网站，在这里你可以将你的文档整理成书并发布，方便阅读。

　　gitbook网站：

　　本文主要讲解如何在gitbook网站上发布图书文档，并使用gitbook提供的工具在本地开发图书文档并部署到自己的服务中

　　在此之前，您需要做如下准备：

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

　　这种方式就是用github网站加上gitbook网站来创建书籍。

　　首先需要有一个github账号，然后在github网站创建一个repo仓库来存放书籍的内容。

　　注意：gitbook网站 有时需要使用代理打开。

　　2.1 登录gitbook网站

　　gitbook网站 支持用github账号直接登录，建议直接用github账号登录。

　　打开 gitbook网站：

　　点击右上角的 Sign In 登录，然后选择 Sign in with GitHub 使用 github 账号登录。

　　首次登录gitbook网站时，需要github网站的认证，还需要在github网站的注册邮箱点击确认。

　　

　　2.2 创建书本2.2.1 单击新建书本按钮

　　登录网站后，点击右上角的用户图标，然后选择您的*敏*感*词*。然后你会看到右上角的+新建按钮，点击这个按钮创建一本书。

　　

　　或者在gitbook的dashboard页面有一个New Book按钮，点击创建一本书：

　　

　　或者打开这个链接，直接进入图书创作页面：

　　2.2.2 在创建书中选择github

　　进入新页面后，找到左侧的GITHUB选项。

　　第一次需要点击右边的安装github集成。

　　这时候会跳转到github页面安装这个插件。可以选择所有仓库或某个仓库，然后点击安装进行安装，输入github密码完成安装。

　　此时返回gitbook新页面刷新，选择github后，右侧会出现如下选项：

　　填写选项后，单击创建书籍按钮。

　　

　　注意：书名必须是英文，因为这里要作为书名的链接（创建成功后可以修改名字）。

　　点击创建书籍按钮后，会出现书籍页面，然后刷新页面，然后点击关于。

　　

　　然后点击右侧的阅读按钮进行阅读。

　　

　　进入阅读后，效果如下：

　　

　　此时已经在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网站上看到更新的内容。有时需要很长时间才能更新。最终效果如下图所示：

　　

　　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

　　如果出现版本号，则表示已安装。如果没有找到这个命令，则进入节点官网：，选择下载，选择对应的操作系统，然后下载安装。

　　gitbook命令行工具推荐nodejs版本为v4.0.0或以上。如果版本太低，可以看下面的教程升级版本到v4.0.0或以上：

　　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

　　

　　安装成功后，可以使用 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 文件是项目的介绍文件。

　　总结.md是gitbook书籍的目录。

　　

　　如果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

　　

　　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

　　然后，根据终端的提示，在浏览器中打开：4000查看书籍，效果如下图：

　　

　　注意：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

　　我也在网上找了一个包：，你可以试试

　　3.6 将项目部署到 GitHub Pages

　　这部分需要用到git和github网站。如果您不知道如何操作，请在 Internet 上搜索文档。

　　由于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://.github.io/

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 -

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

　　文件保存后，在终端执行以下命令，将生成的项目push到github仓库的gh-pages分支：

　　bash deploy.sh

　　执行成功后，打开你的github仓库，选择branch分支。你会发现还有一个额外的 gh-pages 分支。打开这个分支后，里面会有一个 index.html 文件。显示部署的代码上传成功。

　　注意：如果没有gh-pages分支说明部署不成功，请检查刚才执行的终端，看哪里报错，解决错误，直到部署成功。

　　3.6.4 配置GitHub页面显示网站

　　在github网站上的repository中，点击Settings -> GitHub Pages option -> Source，选择gh-pages分支然后点击Save按钮，然后你会在GitHub Pages下看到一个URL，这个URL就是最后的< @网站。

　　最终效果如下图所示：

　　

　　3.7 部署到 GitHub Pages 的一些示例

　　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"

}

}

　　更多配置参数：

　　4.1 book.json 中一些主要参数的说明4.1 配置默认主题

　　可以配置默认主题做以下效果。

　　比如侧边栏菜单显示标题编号，可以在配置文件的pluginsConfig参数中写入如下字段：

　　{

"pluginsConfig": {

"theme-default": {

"showLevel": true

}

}

}

　　效果如下：

　　

　　5. 一些有用的 gitbook 插件

　　gitbook插件可以解决侧边栏导航无法收缩、内置搜索不支持中文等一些不方便的地方。

　　使用插件书网站会更加灵活美观。

　　由于插件较多，请参考我的另一篇文章文章：

　　参考

　　gitbook 的配置文件 book.json 的说明

　　gitbook 工具文档

　　GitBook 编辑器