当前位置:   article > 正文

gitbook使用教程

gitbook怎么使用

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的目录,内容格式如下:

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

此时项目目录结构:

  1. .
  2. ├── README.md
  3. ├── SUMMARY.md
  4. ├── doc
  5. │   └── a.md
  6. └── javascript
  7. └── 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:

  1. node -v
  2. 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命令进行全局安装:

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

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

  1. gitbook --version
  2. CLI version: 2.3.2
  3. GitBook version: 3.2.3

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

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

3.2 初始化一本书

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

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

  1. mkdir book
  2. cd book

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

  1. ~ gitbook init
  2. warn: no summary file in this book
  3. info: create README.md
  4. info: create SUMMARY.md
  5. info: initialization is finished

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

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

  1. * [项目介绍](README.md)
  2. * http
  3. * [http说明](doc/http/http解析.md)
  4. * [tcp说明](doc/http/tcp/tcp说明.md)
  5. * [udp说明](doc/http/tcp/udp/udp说明.md)
  6. * HTML
  7. * [HTML5-特性说明](doc/html/HTML5-特性说明.md)

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

  1. ~ gitbook init
  2. info: create doc/http/http解析.md
  3. info: create doc/http/tcp/tcp说明.md
  4. info: create doc/http/tcp/udp/udp说明.md
  5. info: create doc/html/HTML5-特性说明.md
  6. info: create SUMMARY.md
  7. info: initialization is finished

clipboard.png

3.3 本地启动服务编写书籍

终端打开项目目录,使用gitbook serve启动服务:

  1. ~ gitbook serve
  2. Live reload server started on port: 35729
  3. Press CTRL+C to quit ...
  4. info: 7 plugins are installed
  5. info: loading plugin "livereload"... OK
  6. ……
  7. info: loading plugin "theme-default"... OK
  8. info: found 5 pages
  9. info: found 0 asset files
  10. info: >> generation finished with success in 2.1s !
  11. Starting server ...
  12. Serving book on http://localhost:4000

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

3.4 文档打包

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

  1. ~ gitbook build
  2. info: 7 plugins are installed
  3. info: 6 explicitly listed
  4. info: loading plugin "highlight"... OK
  5. info: loading plugin "search"... OK
  6. info: loading plugin "lunr"... OK
  7. info: loading plugin "sharing"... OK
  8. info: loading plugin "fontsettings"... OK
  9. info: loading plugin "theme-default"... OK
  10. info: found 5 pages
  11. info: found 0 asset files
  12. info: >> generation finished with success in 1.0s !

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

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

3.5 项目部署到GitHub Pages

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

由于gitbook生成的项目跟文档的源码是两个部分,所以可以把文档放到master分支上,部署的网站放到gh-pages 分支。
1、首先需要在github上创建公共一个仓库。
2、在项目中创建一个.gitignore文件,内容如下:

  1. # 忽略gitbook生成的项目目录
  2. _book

然后终端打开项目,输入如下命令,来提交文档源码:

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

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

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

  1. #!/usr/bin/env sh
  2. echo '开始执行命令'
  3. # 生成静态文件
  4. echo '执行命令:gitbook build .'
  5. gitbook build .
  6. # 进入生成的文件夹
  7. echo "执行命令:cd ./_book\n"
  8. cd ./_book
  9. # 初始化一个仓库,仅仅是做了一个初始化的操作,项目里的文件还没有被跟踪
  10. echo "执行命令:git init\n"
  11. git init
  12. # 保存所有的修改
  13. echo "执行命令:git add -A"
  14. git add -A
  15. # 把修改的文件提交
  16. echo "执行命令:commit -m 'deploy'"
  17. git commit -m 'deploy'
  18. # 如果发布到 https://<USERNAME>.github.io/<REPO>
  19. echo "执行命令:git push -f https://github.com/yulilong/book.git master:gh-pages"
  20. git push -f https://github.com/yulilong/book.git master:gh-pages
  21. # 返回到上一次的工作目录
  22. echo "回到刚才工作目录"
  23. cd -

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

文件保存后,在终端执行如下命令开始把最终项推送到gh-pages分支:

bash deploy.sh

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

3.6 一些部署到GitHub Pages的例子

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

参考资料

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

声明:本文内容由网友自发贡献,不代表【wpsshop博客】立场,版权归原作者所有,本站不承担相应法律责任。如您发现有侵权的内容,请联系我们。转载请注明出处:https://www.wpsshop.cn/w/人工智能uu/article/detail/773321
推荐阅读
  

闽ICP备14008679号