Gitbook 命令行工具

<br/ >

本文已停止更新，點擊 此鏈接 查看本文最新內容 ！！！

1、Gitbook 簡介

1.1 Gitbook

• GitBook 是一個基於 Node.js 開發的命令行工具，使用它可以很方便的管理電子書，GitBook 是目前最流行的開源書籍寫作方案。

• 使用 GitBook 可以讓創作者專注寫作，自由的揮灑，不必太多的關心內容排版、發布和版本管理等問題。

• 除了通過 GitBook 命令行管理電子書外，還可以在線或者使用桌面編輯器 Gitbook Editor 來編寫和管理電子書。

• 對於新手來說，推薦使用 Gitbook Editor 來編寫和管理電子書，因為它集成了 GitBook 命令、Markdown 編器和 Git 的功能，內容通過 Git 可與 gitbook.com / Gitlab / GitHub 同步，方便版本管理和團隊協作。

• 可對於程序員或熟悉 Git 和 Markdown 的人，更推薦使用 GitBook 命令行 + Typora + SourceTree 來編寫和管理電子書。使用專業工具做專業的事，比 Gitbook Editor 高效很多。

• GitBook 是開源的。

1.2 GitBook 功能

• 支持 Markdown 或 AsciiDoc 語法。
• 可導出靜態站點或電子書（PDF、epub、mobi）。
• 支持多語言。
• 可設置封面。
• 支持變量、模板和模板繼承。
• 有豐富的插件。

1.3 GitBook 的工具組合

• Node.js：為了使用 npm 安裝 GitBook，一定要先安裝 Node.js。
• GitBook 命令：基於 Node.js 開發的命令行工具，用於創建和管理電子書。
• Markdown：GitBook 使用 Markdown 來寫作，作者再也不用擔心排版了。
• Git：GitBook 使用 Git 管理寫作內容，方便多人協作和版本管理。
• Github/Gitlab：跟代碼一樣，寫作的內容可以托管在 Github 或 Gitlab 中。
• gitbook.com：用於在線編寫、發布和托管電子書的網站。

1.4 GitBook 的使用場景

• 搭建公司內部的文檔平台，用於公司內部的資料共享。
• 發表開源的電子書，用於在互聯網上共享自己的知識，普惠大眾。

2、Gitbook 環境配置

2.1 安裝 Node.js

• 因為 GitBook 是使用 Node.js 開發的，需要通過 Node.js 包管理工具 NPM 安裝，所以在開始之前要先把 Node.js 安裝好。

2.2 安裝 GitBook

• 使用 NPM 安裝 GitBook 的命令行工具。

  $ sudo npm install gitbook-cli -g
  

• 安裝完成后查看 GitBook 的版本。

  $ gitbook --version
  

• 更新 GitBook 命令。

  $ npm update gitbook-cli -g
  

• 卸載 GitBook 命令。

  $ sudo npm uninstall gitbook-cli -g
  

• 注意：

  • 本例中使用的是全局安裝 GitBook 命令，還有一種安裝方式是本地安裝，兩種方式有什么不同呢？

    • 本地安裝：安裝包會被下載到當前所在目錄，因此只能在當前目錄下使用。
    • 全局安裝：安裝包會被下載到到特定的系統目錄下，安裝包能夠在所有目錄下使用。

  • 例如，查看 macOS 下全局安裝被安裝到了哪里？

    $ which gitbook
    /usr/local/bin/gitbook
    

    • GitBook 被安裝到了 /usr/local/bin/ 目錄下，因此可以全局使用。

2.3 快速開始 GitBook

• 1）初始化 GitBook

  # 創建 mygitbook 文件夾，並切換到這個文件夾下面
  $ mkdir mygitbook && cd mygitbook
  
  # 初始化 gitbook 工作目錄，創建必要的文件
  $ gitbook init
  warn: no summary file in this book
  info: create README.md
  info: create SUMMARY.md
  info: initialization is finished
  

  • 然后會初始化 GitBook 目錄，創建兩個 md 格式的文件 README.md 和 SUMMARY.md

    • README.md - 項目的介紹都寫在這個文件里。
    • SUMMARY.md - GitBook 的目錄結構在這里配置。

• 2）定義目錄結構

  • 兩種方法

    • 在 SUMMARY.md 文件中定義目錄結構有兩種方法。

      • 方法 ➊. 先定義好目錄結構，通過 gitbook init 自動生成目錄結構對應的文件夾和 Markdown 文件。

      • 方法 ➋. 先創建好文件夾和 Markdown 文件再來編輯目錄結構。

  • SUMMARY.md

    • SUMMARY.md 的目錄結構長什么樣？看下面：

      # Summary
      
      * [項目簡介](README.md)
      * [快速開始](docs/快速開始.md)
       * [環境搭建](docs/環境搭建.md)
       * [簡單使用](docs/簡單使用.md)
      * [學入學習](docs/深入學習) 
      

  • 這個目錄建好以后在根目錄下執行命令：

    $ gitbook init
    

  • 那些沒有的目錄和文件都會被創建：

    info: create docs/快速開始.md
    info: create docs/環境搭建.md
    info: create docs/簡單使用.md
    info: create docs/深入學習.md
    info: create SUMMARY.md
    info: initialization is finished
    

    • gitbook init 只支持生成兩級目錄。

• 3）啟動服務

  • 在根目錄執行命令：

    $ gitbook serve
    

    • 結果：

      Live reload server started on port: 35729
      Press CTRL+C to quit ...
      
      info: 7 plugins are installed
      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 5 pages
      info: found 0 asset files
      info: >> generation finished with success in 1.9s !
      
      Starting server ...
      Serving book on http://localhost:4000       # 注意瀏覽地址
      

  • 執行 gitbook serve 命令后，會先編譯書籍 gitbook build，如果沒有問題會打開一個 Web 服務器，默認監聽 4000 端口。如果編譯有問題，會拋出錯誤信息。

  • 快速啟動 GitBook 服務器腳本下載，點擊查看軟件下載密碼獲取方法。

• 4）查看效果

  • 用瀏覽器打開 http://localhost:4000/ 或 http://127.0.0.1:4000/ 查看顯示書籍的效果。

    

  • 如果想發給別人看，把 localhost 換成自己電腦的 IP 地址。