Skip to content

Latest commit

 

History

History
672 lines (476 loc) · 24 KB

using_gitbook_write_book.md

File metadata and controls

672 lines (476 loc) · 24 KB
Raw

正如你看到的，这本书就是使用gitbook撰写的

安装gitbook

  • 安装Node.js

参考 在 Windows、Mac OS X 與 Linux 中安裝 Node.js 網頁應用程式開發環境

我前期使用Hexo撰写blog，已经安装了node，使用以下命令验证

node -v

如果没有安装，可以使用nvm来管理node.js版本。注意：安装稳定版本

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.2/install.sh | bash
nvm install stable

安装node.js之后，使用which node可以看到安装目录是用户目录下~/.nvm/versions/node/v8.6.0/bin/node

  • 安装Gitbook

使用NMP安装Gitbook - 参考 gitbllk-cli

npm install -g gitbook-cli

请使用nvm来安装node，这样可以在自己的用户目录下安装和管理各种版本node，就可以避免安装系统目录node，也就不需要使用sudo命令。

(不建议使用系统的node.js)如果使用系统范围的node.js，需要使用命令sudo npm install gitbook -g

安装完成后，使用以下命令验证是否安装成功，如果还没有安装gitbook（如前述只安装了gitbook-cli）则会自动安装稳定版本

gitbook -V

上述这个命令会安装稳定版本，如果要指定安装版本，例如安装alpha版本，则先检查可安装版本

gitbook ls-remote

然后安装pre版本

gitbook fetch pre

此时会看到gitbook被安装到$HOME/.gitbook/versions/4.0.0-alpha.4。并且，为了能够默认使用这个版本，还需要做一个软链接

cd $HOME/.gitbook/versions/
ln -s 4.0.0-alpha.4 latest

此时再验证版本就会看到

gitbook -V

显示输出使用了alpha版本，而不会去安装stable版本

CLI version: 2.3.0
GitBook version: latest (4.0.0-alpha.4)

升级Gitbook

检查已经安装的版本

gitbook ls

查看远程版本

gitbook ls-remote

以上显示gitbook可安装版本，并且有Tag为latest稳定版本和pre的测试版本。

安装特定版本，例如安装alpha版本

gitbook fetch 4.0.0-alpha.4

安装预发布版本(根据gitbook ls-remote提示的版本标签)

gitbook fetch pre

升级最新稳定版本

gitbook update

如果要使用pre版本，则要使用

gitbook update pre

卸载稳定版本，准备改用pre版本

gitbook uninstall 3.2.2

设置某个本地目录作为最新版本

gitbook alias /opt/mygitbook latest

上述命令实际上是在 $HOME/.gitbook/versions 目录下的多个gitbook版本，创建了一个软链接

latest -> /opt/mygitbook

如果要使用特定版本来build文档，可以使用

gitbook build ./mybook --gitbook=4.0.0-alpha.4

参考 Configuration 可以通过设置gitbook文档目录下的book.json文件配置来调整GitBook编译所使用的软件版本。例如，想使用最新的4.0.0-alpha.4，可以使用如下配置

{
  "gitbook": "4.0.0-alpha.4",
  ...
}

这样使用命令gitbook build时候就不需要再增加--gitbook=4.0.0-alpha.4作为参数，简化命令。

不过，为了能够更加通用，实际我是在 $HOME/.gitbook/versions 执行以下命令，将4.0.0-alpha.4软链接成latest，这样后续所有执行gitbook就不需要再强制版本了（也不会再去下载latest版本）

cd $HOME/.gitbook/versions
unlink latest
ln -s 4.0.0-alpha.4 latest

此时再使用gitbook -V验证可以看到如下输出显示已经升级到最新的alpha版本

CLI version: 2.3.0
GitBook version: latest (4.0.0-alpha.4)
  • 将gitbook 3.2.2升级到4.0.0-beta版本后，还要注意，如果同时升级过node.js版本，需要在node.js中使用npm安装升级对应插件：
npm install gitbook-plugin-codeblock-filename -g

npm install react react-dom react-disqus-thread gitbook-plugin-disqus -g

react react-dom react-disqus-thread gitbook-plugin-disqus这些npm包需要一起依赖安装，上述命令会全局安装到nvm目录下。

不过，最好还是在文档目录下编辑好book.json文件

{
  "gitbook": "4.0.0-alpha.4",
  "plugins": ["disqus","toggle-chapters"],
  "pluginsConfig": {
    "disqus": {
      "shortName": "XXXXXX"
    }
  }
}

然后执行以下命令先删除掉旧版本插件，然后重新安装插件

rm -rf node_modules/*
gitbook install

升级到4.0.0-alpha.4之后的处理

  • 在文档目录执行gitbook serve时候出现如下报错
Error: ENOENT: no such file or directory, open '/Users/huatai/.gitbook/versions/4.0.0-alpha.4/node_modules/gitbook-plugin-livereload/_assets/plugin.js'

解决方法参考常规的插件安装

cd /Users/huatai/.gitbook/versions/4.0.0-alpha.4
npm i gitbook-plugin-livereload

提示gitbook-plugin-livereload是在/Users/huatai/.gitbook/versions/4.0.0-alpha.4目录（包含了packages.json配置文件），所以在这个执行npm i gitbook-plugin-livereload就会安装模块到该目录下的node_modules子目录中。这是npm的常规安装方法，并且这个本地安装方法会读取package.json文件来安装对应模块版本。 - 参考 Installing npm packages locally

但是，我发现上述本地安装gitbook-plugin-livereload模块实际上只在node_modules/gitbook-plugin-livereload更新了编译安装配置文件，实际上操作方法应该是进入node_modules/gitbook-plugin-livereload后执行npm install命令，所以再次修复

cd /Users/huatai/.gitbook/versions/4.0.0-alpha.4/node_modules/gitbook-plugin-livereload
npm install

上述过程存在编译错误

> [email protected] postinstall /Users/huatai/.gitbook/versions/4.0.0-alpha.4/node_modules/gitbook-plugin-livereload/node_modules/spawn-sync
> node postinstall


> [email protected] prepublish /Users/huatai/.gitbook/versions/4.0.0-alpha.4/node_modules/gitbook-plugin-livereload
> npm run build-js


> [email protected] build-js /Users/huatai/.gitbook/versions/4.0.0-alpha.4/node_modules/gitbook-plugin-livereload
> gitbook-plugin build ./src/index.js ./_assets/plugin.js

events.js:160
      throw er; // Unhandled 'error' event
      ^

Error: Couldn't find preset "es2015" relative to directory "/Users/huatai/.gitbook/versions/4.0.0-alpha.4" while parsing file: /Users/huatai/.gitbook/versions/4.0.0-alpha.4/node_modules/gitbook-plugin-livereload/src/index.js
    at /Users/huatai/.gitbook/versions/4.0.0-alpha.4/node_modules/gitbook-plugin-livereload/node_modules/babel-core/lib/transformation/file/options/option-manager.js:292:19
    at Array.map (native)
    at OptionManager.resolvePresets (/Users/huatai/.gitbook/versions/4.0.0-alpha.4/node_modules/gitbook-plugin-livereload/node_modules/babel-core/lib/transformation/file/options/option-manager.js:274:20)
    at OptionManager.mergePresets (/Users/huatai/.gitbook/versions/4.0.0-alpha.4/node_modules/gitbook-plugin-livereload/node_modules/babel-core/lib/transformation/file/options/option-manager.js:263:10)
    at OptionManager.mergeOptions (/Users/huatai/.gitbook/versions/4.0.0-alpha.4/node_modules/gitbook-plugin-livereload/node_modules/babel-core/lib/transformation/file/options/option-manager.js:248:14)
    at OptionManager.init (/Users/huatai/.gitbook/versions/4.0.0-alpha.4/node_modules/gitbook-plugin-livereload/node_modules/babel-core/lib/transformation/file/options/option-manager.js:367:12)
    at File.initOptions (/Users/huatai/.gitbook/versions/4.0.0-alpha.4/node_modules/gitbook-plugin-livereload/node_modules/babel-core/lib/transformation/file/index.js:216:65)
    at new File (/Users/huatai/.gitbook/versions/4.0.0-alpha.4/node_modules/gitbook-plugin-livereload/node_modules/babel-core/lib/transformation/file/index.js:139:24)
    at Pipeline.transform (/Users/huatai/.gitbook/versions/4.0.0-alpha.4/node_modules/gitbook-plugin-livereload/node_modules/babel-core/lib/transformation/pipeline.js:46:16)
    at Babelify._flush (/Users/huatai/.gitbook/versions/4.0.0-alpha.4/node_modules/gitbook-plugin-livereload/node_modules/babelify/index.js:27:24)

npm ERR! Darwin 16.4.0
npm ERR! argv "/Users/huatai/.nvm/versions/node/v6.9.4/bin/node" "/Users/huatai/.gitbook/versions/4.0.0-alpha.4/node_modules/.bin/npm" "run" "build-js"
npm ERR! node v6.9.4
npm ERR! npm  v3.10.9
npm ERR! code ELIFECYCLE
npm ERR! [email protected] build-js: `gitbook-plugin build ./src/index.js ./_assets/plugin.js`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the [email protected] build-js script 'gitbook-plugin build ./src/index.js ./_assets/plugin.js'.
npm ERR! Make sure you have the latest version of node.js and npm installed.
npm ERR! If you do, this is most likely a problem with the gitbook-plugin-livereload package,
npm ERR! not with npm itself.
npm ERR! Tell the author that this fails on your system:
npm ERR!     gitbook-plugin build ./src/index.js ./_assets/plugin.js
npm ERR! You can get information on how to open an issue for this project with:
npm ERR!     npm bugs gitbook-plugin-livereload
npm ERR! Or if that isn't available, you can get their info via:
npm ERR!     npm owner ls gitbook-plugin-livereload
npm ERR! There is likely additional logging output above.

npm ERR! Please include the following file with any support request:
npm ERR!     /Users/huatai/.gitbook/versions/4.0.0-alpha.4/node_modules/gitbook-plugin-livereload/npm-debug.log

npm WARN [email protected] license should be a valid SPDX license expression
npm ERR! Darwin 16.4.0
npm ERR! argv "/Users/huatai/.nvm/versions/node/v6.9.4/bin/node" "/Users/huatai/.nvm/versions/node/v6.9.4/bin/npm" "install"
npm ERR! node v6.9.4
npm ERR! npm  v3.10.10
npm ERR! code ELIFECYCLE
npm ERR! [email protected] prepublish: `npm run build-js`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the [email protected] prepublish script 'npm run build-js'.
npm ERR! Make sure you have the latest version of node.js and npm installed.
npm ERR! If you do, this is most likely a problem with the gitbook-plugin-livereload package,
npm ERR! not with npm itself.
npm ERR! Tell the author that this fails on your system:
npm ERR!     npm run build-js
npm ERR! You can get information on how to open an issue for this project with:
npm ERR!     npm bugs gitbook-plugin-livereload
npm ERR! Or if that isn't available, you can get their info via:
npm ERR!     npm owner ls gitbook-plugin-livereload
npm ERR! There is likely additional logging output above.

npm ERR! Please include the following file with any support request:
npm ERR!     /Users/huatai/.gitbook/versions/4.0.0-alpha.4/node_modules/gitbook-plugin-livereload/npm-debug.log

参考 Error: Couldn't find preset “es2015” relative to directory “/Users/username” 先执行

npm install babel-cli babel-preset-es2015

但是报错依旧，另外发现./_assets/plugin.js文件内容是空的

尝试重新安装一次（重新安装前先全局安装一次 babel-cli babel-preset-es2015）

gitbook uninstall 4.0.0-alpha.4
unlink ~/.gitbook/versions/latest
npm install babel-cli babel-preset-es2015 -g

gitbook fetch pre
cd ~/.gitbook/versions
ln -s 4.0.0-alpha.4 latest

cd 4.0.0-alpha.4/node_modules/gitbook-plugin-livereload
npm install

没有解决，暂时放弃尝试，回退到稳定版本

cd ~/.gitbook/versions
unlink latest

gitbook uninstall 4.0.0-alpha.4
gitbook update

此时安装版本是稳定版本3.2.2

重新安装文档目录中的插件

cd ~/my_gitbook
gitbook install
  • 无法找到gitbook-core模块

还有报错

Error: Cannot find module 'gitbook-core'

尝试再次安装gitbook-core模块

cd /Users/huatai/.nvm/versions/node/v6.9.4/lib/node_modules/gitbook-cli
npm i gitbook-core -g

必须进入lib/node_modules/gitbook-cli才能执行上述安装命令，需要读取该目录下的package.json

  • TypeError: Cannot read property 'Page' of undefined

修复了gitbook-core模块问题后，又遇到不能读取Page属性问题

error: error while generating page "README.md":

TypeError: Cannot read property 'Page' of undefined

使用 gitbook -d serve 命令详细排查显示错误

...
    at /Users/huatai/.gitbook/versions/4.0.0-alpha.4/node_modules/immutable/dist/immutable.js:2701:43
    at List.__iterate (/Users/huatai/.gitbook/versions/4.0.0-alpha.4/node_modules/immutable/dist/immutable.js:2208:13

显示报错和模块immutable有关

使用GitBook

  • 初始化目录cloud-atlas

      gitbook init cloud-atlas

我的个人"云图" cloud-atlas.huatai.me 记录自己在云计算领域的技术探索。

进入cloud-atlas.huatai.me目录可以看到该目录下有2个文件，除此之外什么也没有

README.md
SUMMARY.md
  • 本地预览自动生成

编辑好初步的文档之后（例如编辑 README.md ）可以使用gitbook命令启用一个本地的服务进行预览

gitbook serve cloud-atlas

此时会在 cloudatlas 目录下生成一个子目录_book包含了所有生成的静态网站文件。

  • 使用build参数将静态文件生成到指定目录

也可以将静态文件生成到指定目录下，这样就可以方便打包输出的静态文件

mkdir /tmp/gitbook
gitbook build cloudatlas.huatai.me --output=/tmp/gitbook

通过浏览器访问 http://localhost:4000 来查看页面效果

输出pdf

要输出PDF文件，先安装gitbook-pdf

npm install gitbook-pdf -g

这里安装报错显示

Downloading http://cdn.bitbucket.org/ariya/phantomjs/downloads/phantomjs-1.9.7-macosx.zip
Saving to /usr/local/lib/node_modules/gitbook-pdf/node_modules/phantomjs/phantomjs/phantomjs-1.9.7-macosx.zip
Receiving...
Error requesting archive.
Status: 403
...
npm ERR! [email protected] install: `node install.js`
npm ERR! Exit status 1

参考Yeoman generator always get some error，尝试

PHANTOMJS_CDNURL=https://bitbucket.org/ariya/phantomjs/downloads npm install phantomjs

虽然正确安装了 phantomjs-1.9.8，但是安装gitbook-pdf同样失败。后来发现，应该是这个安装 gitbook-pdf 依赖安装指定版本，所以参考 npm-install安装指定版本

PHANTOMJS_CDNURL=https://bitbucket.org/ariya/phantomjs/downloads npm install [email protected]

还没有成功

GitBook简明使用手册

首页

详细的Gitbook使用参考 GitBook使用指南

默认文件README.md，这个文件是介绍网站的的说明，也是GitBook显示在首页的内容

在Gitbook的2.0.0之后，可以在 book.json 中指定文件作为README

{
    "structure": {
    "readme": "myIntro.md"
    }
}

章节

GitBook使用 SUMMARY.md来定义章节和子章节

# Summary

* [Chapter 1](chapter1.md) 
* [Chapter 2](chapter2.md)
* [Chapter 3](chapter3.md)

子章节案例：

# Summary

* [Part I](part1/README.md)
    * [Writing is nice](part1/writing.md)
    * [GitBook is nice](part1/gitbook.md)
* [Part II](part2/README.md)
    * [We love feedback](part2/feedback_please.md)
    * [Better tools for authors](part2/better_tools.md)# Summary
* [Part I](part1/README.md)
    * [Writing is nice](part1/writing.md)
    * [GitBook is nice](part1/gitbook.md)
* [Part II](part2/README.md)
    * [We love feedback](part2/feedback_please.md)
    * [Better tools for authors](part2/better_tools.md)

MarkDown

GitBook使用GitHub favorited markdown格式

  • 链接

    • 可以直接引用URL [Google官网](https://www.google.com)

    • 也可以引用本网站的文档，如 [内核进程状态参考](../../../../os/linux/kernel/process_stat_indicates.md)

    • 可以直接引用相同目录下的文档，如 [ssh portfording设置](ssh_portfording.md)：不过需要注意，所引用的文档必须在summary.md中已经定义，这样才能够创建html文件，并正确引用

    • 或者将超链接都集中到文档末尾（假如有多个相同的链接倒是比较方便，不过我没使用这个格式）

      You can use numbers for reference-style link definitions

发布

  • 首先在gitbook 注册一个账号

注册时候会发送一个确认邮件到你的邮箱，如果邮箱地址和你的gravatar注册头像一致，就会自动显示在gitbook上（也可以在设置中修改）。

  • 在gitbook的设置Profile中，其中有一项是Connect GitHub Account。使用这个管理功能，github会通过oauth方式，给予gitbook访问 公开的仓库 权限（这步需要么？）

  • 创建图书，在图书页面选择 github ，此时选择gitbub的某个公开的仓库（也就是你前面将自己的gitbook推送的仓库），通过关联后，这个仓库的书就会出现在在 https://{author}.gitbooks.io/{book}/

例如，我的有关云计算的书 Cloud Atlas https://huataihuang.gitbooks.io/cloud-atlas/

插件

gitbook插件可以给你的电子书带来更多的功能，请尝试吧！

GitBook + PlantUML 以 Markdown 快速製作 UML 教材

生成电子书

参考 Generating eBooks and PDFs

GitBook可以生成不同格式的电子书(ePub,Mobi,PDF)，需要安装一个 ebook-convert 组件(属于Calibre application，在Linux平台可以通过发行版安装)。

macOS可以安装Calibre application后用以下命令创建一个软链接：

sudo ln -s ~/Applications/calibre.app/Contents/MacOS/ebook-convert /usr/bin
  • 生成电子书
# Generate a PDF file
$ gitbook pdf ./ ./mybook.pdf

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

# Generate a Mobi file
$ gitbook mobi ./ ./mybook.mobi
  • 电子书封面可以使用 autocover plugin创建，只需要提供两种大小的 cover.jpg 和 cover_small.jpg ，建议：
    • Size of 1800x2360 pixels for cover.jpg, 200x262 for cover_small.jpg
    • No border
    • Clearly visible book title
    • Any important text should be visible in the small version

升级

升级到GitBook 3.x 时候，在执行 gitbook serve 命令的终端提示

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

info: 8 plugins are installed
info: loading plugin "disqus"... OK
info: loading plugin "livereload"... OK
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 348 pages
info: found 111 asset files
warn: "sections" property is deprecated, use page.content instead

检查了 node_modules 目录下模块，发现是 gitbook-plugin-codeblock-filename 使用了 page.sections ，但是观察了最新的gitbook，发现已经支持章节缩进，所以就去除掉多个插件，只保留disqus插件。

发现访问 http://127.0.0.1:35729 不能正常展示，页面只提示

{"tinylr":"Welcome","version":"0.2.1"}

但是依然出现同样无法展示问题。参考 Gitbookのインストール（2016/1/19時点） ，原来这个页面{"tinylr":"Welcome","version":"0.2.1"}是表示安装gitbook成功。

但是，发现过了很久，大约 380 秒以后才提示出现

info: >> generation finished with success in 380.2s !

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

原来升级到新版本之后，在重新绘制页面出现了非常缓慢的问题。在 Generating slowly when the file number is large #1497 提出了同样的问题，显示升级到 3.x 之后build非常缓慢。我自己测试了一下，差不多一个文件需要1秒钟，期间单个CPU负载满负荷运行。

Setup and Installation of GitBook 提供了如下debug的方法

gitbook build ./ --log=debug --debug

此外可以统计各阶段的使用时间

gitbook build --timing

显示输出大部分时间消耗在template.render

debug: 0.0% of time spent in "call.hook.finish:before" (1 times) :
debug:     > Total: 1ms | Average: 1ms
debug:     > Min: 1ms | Max: 1ms
debug: ---------------------------
debug: 0.0% of time spent in "call.hook.init" (1 times) :
debug:     > Total: 1ms | Average: 1ms
debug:     > Min: 1ms | Max: 1ms
debug: ---------------------------
debug: 0.0% of time spent in "call.hook.config" (1 times) :
debug:     > Total: 2ms | Average: 2ms
debug:     > Min: 2ms | Max: 2ms
debug: ---------------------------
debug: 0.0% of time spent in "plugins.findForBook" (1 times) :
debug:     > Total: 52ms | Average: 52ms
debug:     > Min: 52ms | Max: 52ms
debug: ---------------------------
debug: 0.0% of time spent in "parse.listAssets" (1 times) :
debug:     > Total: 98ms | Average: 98ms
debug:     > Min: 98ms | Max: 98ms
debug: ---------------------------
debug: 0.1% of time spent in "call.hook.page:before" (348 times) :
debug:     > Total: 187ms | Average: 1ms
debug:     > Min: 0ms | Max: 5ms
debug: ---------------------------
debug: 0.1% of time spent in "plugin.load" (8 times) :
debug:     > Total: 194ms | Average: 24ms
debug:     > Min: 1ms | Max: 147ms
debug: ---------------------------
debug: 0.1% of time spent in "call.hook.finish" (1 times) :
debug:     > Total: 259ms | Average: 259ms
debug:     > Min: 259ms | Max: 259ms
debug: ---------------------------
debug: 0.1% of time spent in "parse.book" (1 times) :
debug:     > Total: 270ms | Average: 270ms
debug:     > Min: 270ms | Max: 270ms
debug: ---------------------------
debug: 0.1% of time spent in "parse.listPages" (1 times) :
debug:     > Total: 300ms | Average: 300ms
debug:     > Min: 300ms | Max: 300ms
debug: ---------------------------
debug: 0.4% of time spent in "call.hook.page" (348 times) :
debug:     > Total: 1.36s | Average: 4ms
debug:     > Min: 0ms | Max: 110ms
debug: ---------------------------
debug: 2.2% of time spent in "page.generate" (348 times) :
debug:     > Total: 8.31s | Average: 24ms
debug:     > Min: 11ms | Max: 136ms
debug: ---------------------------
debug: 92.3% of time spent in "template.render" (696 times) :
debug:     > Total: 344.00s | Average: 494ms
debug:     > Min: 0ms | Max: 1.33s
debug: ---------------------------
debug: 17.46s spent in non-mesured sections

回滚gitbook版本

参考 How do I install a previous version of an npm package?

npm view gitbook versions

npm remove [email protected]
npm install [email protected]

上述方法并没有成功，我也尝试重新安装gitbook-cli，发现gitbook-cli安装的2.3.0版本自动安装了gitbook 3.2.2。所以暂时采用在更新了多个文档之后，只执行 gitbook build 生成静态文件，大多数情况下并不需要实时编译。

参考