鵝從未在裡面

Everything will be all right in the end.

platform, gitbook

Ubuntu環境下，快速開始使用gitbook

注意

安裝方式，請參考這篇「gitbook 2.0」，這篇的安裝方式是基於「gitbook 1.5.0」

測試環境

撰寫本文時，測試的環境是

  • 「Xubuntu 14.04 64位元」
  • 「nvm v0.23.2」
  • 「nodejs v0.10.35」
  • 「npm v1.4.28」
  • 「gitbook 1.5.0」

前置作業

請先安裝「nodejs」，可以參考「Ubuntu環境下，如何安裝nvm以及nodejs」這篇的說明。

安裝 gitbook

使用「npm」來安裝「gitbook」。

1
$ npm install gitbook -g

查看「gitbook」的版本

1
$ gitbook version

或

1
$ gitbook --version

或

1
$ gitbook -V

顯示

1
1.5.0

建立工作環境

先建立一本書的資料夾「~/Documents/mybook」，並且切換到該路徑

1
2
$ mkdir ~/Documents/mybook -p
$ cd ~/Documents/mybook

建立「忽略設定檔」

建立「.gitignore」，請參考「ignoring-files–folders」這裡的說明。
這個步驟非必要。

1
2
3
4
5
# https://github.com/github/gitignore/blob/master/GitBook.gitignore

$ wget -c https://raw.githubusercontent.com/github/gitignore/master/GitBook.gitignore -O .gitignore

$ cat .gitignore

下載的「.gitignore」的內容如下

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# Node rules:
## Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
.grunt

## Dependency directory
## Commenting this out is preferred by some people, see
## https://npmjs.org/doc/faq.html#Should-I-check-my-node_modules-folder-into-git
node_modules

# Book build output
_book

# eBook build output
*.epub
*.mobi
*.pdf

建立「README.md」，「SUMMARY.md」這兩個檔案

1
$ touch README.md  SUMMARY.md

啟動server

1
$ gitbook serve

會出現現面的訊息

1
2
3
4
5
6
7
8
Press CTRL+C to quit ...

Live reload server started on port: 35729
Starting build ...
Successfully built!

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

觀看頁面

利用「Firefox」觀看本書首頁。

1
$ firefox http://localhost:4000

更改首頁內容

1
$ echo "# 書名 " > README.md

因為有「Live reload」，所以首頁就會立即顯示剛剛的內容了。

初始化各章節

1
$ vi SUMMARY.md

把下面的內容寫到「SUMMARY.md」。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Summary

This is the summary of my book.

* [chapter 1](content/chapter1/index.md)
	* [section 1](content/chapter1/section1.md)
	* [section 2](content/chapter1/section2.md)
	* [section 3](content/chapter1/section3.md)
	* [section 4](content/chapter1/section4.md)
	* [section 5](content/chapter1/section5.md)
* [chapter 2](content/chapter2/index.md)
	* [section 1](content/chapter2/section1.md)
	* [section 2](content/chapter2/section2.md)
	* [section 3](content/chapter2/section3.md)

然後執行下面的指令，就會把各章節的「原始檔」產生好。

1
$ gitbook init

觀看產生的「原始檔」

1
$ tree content

會看到下面的結構

1
2
3
4
5
6
7
8
9
10
11
12
13
content
├── chapter1
│   ├── index.md
│   ├── section1.md
│   ├── section2.md
│   ├── section3.md
│   ├── section4.md
│   └── section5.md
└── chapter2
    ├── index.md
    ├── section1.md
    ├── section2.md
    └── section3.md

編輯各章節的內容

1
2
3
4
5
6
7
8
9
10
echo "# 第一章 " > 'content/chapter1/index.md'
echo "# 第一章 / 第一節 " > 'content/chapter1/section1.md'
echo "# 第一章 / 第二節 " > 'content/chapter1/section2.md'
echo "# 第一章 / 第三節 " > 'content/chapter1/section3.md'
echo "# 第一章 / 第四節 " > 'content/chapter1/section4.md'
echo "# 第一章 / 第五節 " > 'content/chapter1/section5.md'
echo "# 第二章 " > 'content/chapter2/index.md'
echo "# 第二章 / 第一節" > 'content/chapter2/section1.md'
echo "# 第二章 / 第二節 " > 'content/chapter2/section2.md'
echo "# 第二章 / 第五節 " > 'content/chapter2/section3.md'

一樣基於Live reload，直接就可以在瀏覽器看到變化。

產生其他格式

在執行下面的指令前需要「ebook-convert」這個「工具」，是屬於「calibre」這個套件。

安裝「calibre」。

1
$ sudo apt-get install calibre

測試「ebook-convert」是否存在。

1
$ ebook-convert --version

「pdf」格式

1
$ gitbook pdf

「epub」格式

1
$ gitbook epub

「mobi」格式

1
$ gitbook mobi

分別會產生「book.pdf」 「book.epub」 「book.mobi」這三個檔

1
$ ls book*

會看到下面的訊息

1
book.epub  book.mobi  book.pdf

「gitbook」利用「ebook-convert」的相關原始碼，應該是「lib/generate/ebook/index.js」這個檔。

可以在「 exec(command, function (error, stdout, stderr) {」前，

加入「console.log(‘command: %s’, command);」來印出來「gitbook」如何下「ebook-convert」指令。

gitbook相關網址

參考文章

basic-skill, ebook, gitbook, 基本功
← Prev Next →