GitBook 簡明教程

Modern book format and toolchain using Git and Markdown

這是 GitBook 項目主頁上對 GitBook 的定義。

GitBook 是一個命令行工具。經過它，你可以使用 Git 和 Markdown 來編排書本。而且經過工具能夠自動生成相應的 HTML、PDF 和 epub 格式的文件。

總之，就是好用，好使，加好看。

恰好近日準備經過 GitBook 來寫一些教程，這裏就先簡明介紹一下它的使用。嗯？我寫的什麼教程？ 哈哈，就不告訴你，等寫好了再說 <(￣▽￣)> 哇哈哈…

安裝

由於 GitBook 是一個基於 Node 開發的命令行工具。所以須要您自行配置 Node 和 npm 環境。若是你已經安裝好這些環境以後，GitBook 的安裝只須要一步就能完成！

$ npm install -g gitbook-cli

使用

GitBook 的用法很是簡單，老規矩，先看一下咱們都有哪些命令可使用:

$ gitbook help

  build [book] [output]      build a book
    --format      Format to build to (Default is website; Values are website, json, ebook)
    --log      Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)

  pdf [book] [output]      build a book to pdf
    --log      Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)

  epub [book] [output]      build a book to epub
    --log      Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)

  mobi [book] [output]      build a book to mobi
    --log      Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)

  serve [book]      Build then serve a gitbook from a directory
    --port      Port for server to listen on (Default is 4000)
    --lrport      Port for livereload server to listen on (Default is 35729)
    --watch      Enable/disable file watcher (Default is true)
    --format      Format to build to (Default is website; Values are website, json, ebook)
    --log      Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)

  install [book]      install plugins dependencies

  init [directory]      create files and folders based on contents of SUMMARY.md

實際上咱們最經常使用的命令只有兩個:

• gitbook init: 初始化書籍目錄

• gitbook serve: 在編寫書籍時啓動一個服務器，自動編譯&更新內容，並在瀏覽器中預覽

使用

gitbook init

首先，經過終端(PC 下可以使用命令提示符)進入到你想要書寫內容的目錄，而後執行 gitbook init 命令，以後目錄中會自動生成 README.md 和 SUMMARY.md 兩個文件。

這兩個文件在 GitBook 項目中是必須存在的，其中 README.md 是對書籍的簡單介紹，SUMMARY.md 是對書籍目錄的描述，而且 GitBook 會經過該文件中的目錄描述自動生成對應的目錄和文件。

其中，SUMMARY.md 文件中內容的格式是這樣的:

* [Chapter1](chapter1/README.md)
  * [Section1.1](chapter1/section1.1.md)
  * [Section1.2](chapter1/section1.2.md)
* [Chapter2](chapter2/README.md)

當你修改了 SUMMARY.md 文件中的內容後，你能夠再次使用 gitbook init 來自動生成對應的目錄和文件。

Multi-Languages

若是你要寫的書籍是多語言版，你只須要建立一個 LANGS.md 文件，而後編寫配置內容便可:

* [English](en/)
* [French](fr/)
* [Español](es/)

gitbook serve

書籍目錄結構建立完成之後，咱們就可使用 gitbook serve 來編譯和預覽書籍了：

gitbook serve 命令實際上會首先調用 gitbook build 編譯書籍，完成之後會打開一個 web 服務器，監聽在本地的 4000 端口。

$ gitbook serve

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

info: loading book configuration....OK
info: load plugin gitbook-plugin-highlight ....OK
info: load plugin gitbook-plugin-search ....OK
info: load plugin gitbook-plugin-sharing ....OK
info: load plugin gitbook-plugin-fontsettings ....OK
info: load plugin gitbook-plugin-livereload ....OK
info: >> 5 plugins loaded
info: start generation with website generator
info: clean website generator
info: OK
info: generation is finished

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

以後，你就可使用瀏覽器打開 http://127.0.0.1:4000 查看效果了。就是這麼簡單。

頁面效果以下:

你能夠盡情的使用 Markdown 來編寫文章了，徹底不須要關心樣式和排版呢。

GitBook 編輯器

若是你不喜歡使用命令行，這裏也有 GitBook 可視化編輯器，https://www.gitbook.com/editor/

GitBook.com

GitBook.com 是一個圍繞 GitBook 發行書籍的社區，於 2014 年初創，GitBook.com 提供免費和付費的服務，並且免費帳戶就能夠享受諸多服務，包括：

• 1 本私有書籍

• 託管不限數量的公開書籍

• 售賣不限數量的書籍，並分享 80% 的書籍收入

• 不限數量的協做者

• 免費的在線書籍編輯器

其餘命令

• gitbook build: 會生成相應的 HTML 文件供分發。

• gitbook pdf: 生成 PDF 文件

• gitbook epub: 生成 epub 文件

• gitbook mobi: 生成 mobi 文件

高級技巧

個性化配置

咱們經過配置 book.json 文件來修改 GitBook 在編譯書籍時的行爲，例如：修改書籍的名稱，顯示效果等等。

GitBook 在編譯書籍的時候會讀取書籍源碼頂層目錄中的 book.json，book.json 支持的具體配置請參考官方文檔

安裝插件

你能夠經過 gitbook install 命令來安裝一些諸如 disqus、multipart 這些實用的第三方插件。