devbox
人工智能uu
这个屌丝很懒，什么也没留下！
关注作者
热门标签
热门文章
当前位置:   article > 正文

gitbook使用教程

作者：人工智能uu | 2024-06-30 16:23:22

赞

踩

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.  
  3. npm http fetch GET 304 https://registry.npm.taobao.org/os-tmpdir 100ms (from cache)
  4. npm http fetch GET 304 https://registry.npm.taobao.org/os-homedir 113ms (from cache)
  5. /usr/local/bin/gitbook -> /usr/local/lib/node_modules/gitbook-cli/bin/gitbook.js
  6. + gitbook-cli@2.3.2
  7. 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.  
  3. warn: no summary file in this book 
  4. info: create README.md 
  5. info: create SUMMARY.md 
  6. info: initialization is finished

gitbook init会在空项目中创建README.md和SUMMARY.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.  
  3. info: create doc/http/http解析.md 
  4. info: create doc/http/tcp/tcp说明.md 
  5. info: create doc/http/tcp/udp/udp说明.md 
  6. info: create doc/html/HTML5-特性说明.md 
  7. info: create SUMMARY.md 
  8. info: initialization is finished

clipboard.png

3.3 本地启动服务编写书籍

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

  1. ~ gitbook serve
  2.  
  3. Live reload server started on port: 35729
  4. Press CTRL+C to quit ...
  5.  
  6. info: 7 plugins are installed 
  7. info: loading plugin "livereload"... OK 
  8. ……
  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 2.1s ! 
  14. Starting server ...
  15. Serving book on http://localhost:4000

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

3.4 文档打包

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

  1. ~ gitbook build
  2.  
  3. info: 7 plugins are installed 
  4. info: 6 explicitly listed 
  5. info: loading plugin "highlight"... OK 
  6. info: loading plugin "search"... OK 
  7. info: loading plugin "lunr"... OK 
  8. info: loading plugin "sharing"... OK 
  9. info: loading plugin "fontsettings"... OK 
  10. info: loading plugin "theme-default"... OK 
  11. info: found 5 pages 
  12. info: found 0 asset files 
  13. 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.  
  3. echo '开始执行命令'
  4. # 生成静态文件
  5. echo '执行命令：gitbook build .'
  6. gitbook build .
  7.  
  8. # 进入生成的文件夹
  9. echo "执行命令：cd ./_book\n"
  10. cd ./_book
  11.  
  12. # 初始化一个仓库，仅仅是做了一个初始化的操作，项目里的文件还没有被跟踪
  13. echo "执行命令：git init\n"
  14. git init
  15.  
  16. # 保存所有的修改
  17. echo "执行命令：git add -A"
  18. git add -A
  19.  
  20. # 把修改的文件提交
  21. echo "执行命令：commit -m 'deploy'"
  22. git commit -m 'deploy'
  23.  
  24. # 如果发布到 https://<USERNAME>.github.io/<REPO>
  25. echo "执行命令：git push -f https://github.com/yulilong/book.git master:gh-pages"
  26. git push -f https://github.com/yulilong/book.git master:gh-pages
  27.  
  28. # 返回到上一次的工作目录
  29. echo "回到刚才工作目录"
  30. 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
推荐阅读
相关标签

Copyright © 2003-2013 www.wpsshop.cn 版权所有，并保留所有权利。

  

闽ICP备14008679号