Gitbook 製做文檔教程（一）- Gitbook 入門及使用 GitBook Editor

1、GitBook 簡介

GitBook 是一個基於 Node.js 的命令行工具，可以使用 Github/Git 和 Markdown 來製做精美的電子書、開發文檔等。

GitBook支持輸出多種文檔格式： ·

• 靜態站點：GitBook默認輸出該種格式，生成的靜態站點可直接託管搭載Github Pages服務上；
• PDF：須要安裝gitbook-pdf依賴； ·
• eBook：須要安裝ebook-convert； ·

 

2、GitBook 安裝

 本文以Windows環境安裝及使用示例

2.1 安裝Node.js

下載Node.js：http://nodejs.cn/download/，選擇當前系統合適版本並直接安裝

 

2.2 安裝Gitbook

打開CMD（管理員模式），輸入命令：

npm install gitbook-cli -g

（gitbook-cli 是 GitBook 的一個命令行工具。它將自動安裝所需版本的 GitBook 來構建一本書。 執行下面的命令，查看 GitBook 版本，以驗證安裝成功）

 

2.2 Gitbook初始化

gitbook init

（初始化後，Gitbook默認輸出目錄位於：C:\Users\XXX\GitBook\Library\Import）

 

3、GitBook 項目

3.1 建立Gitbook項目並對項目初始化

你能夠在硬盤任意位置建立項目文件夾，好比新建 D:\book 文件夾用於存放和管理全部項目文檔，再在 D:\book 新建項目文件夾，如新建一個Api接口文檔項目：D:\book\MyApi

 

建完項目目錄，命令行對項目目錄執行初始化：

gitbook init D:\book\MyApi

（gitbook init + 項目目錄 可對指定的目錄執行項目初始化）

 初始化後，能夠看到生成兩個md文件（markdown格式）：

• README.md ： 電子書的前言或簡介 (required) 
• SUMMARY.md：電子書目錄 (optional) 

 

3.2 生成項目靜態網頁

命令行輸入：

gitbook build D:\book\MyApi

 

 等待執行結果，完成後能夠發現項目目錄下多出一個「_book」目錄，點擊該目錄，發現生成以下目錄及文件：

•  gitbook
•  index.html
•  search_index.json

 點擊 index.html，能夠直接打開生成好的靜態網頁

 

 

3.3 運行WEB服務

 命令行輸入：

gitbook serve D:\book\MyApi

 

當命令行顯示以下字符時，表示項目WEB服務已開啓

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

瀏覽器輸入：http://localhost:4000，便可直接打開項目靜態網頁

 

4、使用 GitBook Editor

4.1 下載及安裝GitBook Editor

咱們能夠藉助 GitBook Editor 很方便地去編輯和管理GitBook項目文檔，下載地址：https://legacy.gitbook.com/editor

下載及安裝後打開：

 

 在登陸窗口點擊「Do that later」，先不登陸直接使用，以後點擊「GitBook Editor」菜單 - 「change library path」 ，設置項目存放目錄，這裏咱們選擇 D:\book  做爲項目存放目錄

 

 

 設置好項目目錄後點擊「+New Book」 建立 文檔項目，命名「Api_test」

 

 

 點擊「Confirm」 肯定，建立新的文檔項目

 

點擊右下角「？」按鈕，選擇Markdown 編輯模式

 

 

 

編輯器總體界面簡潔，左側樹形目錄可切換章節及文件目錄，中間爲輸入區，右側爲實時預覽區，頂部爲菜單及文本格式區

點擊「Ctrl+s」保存項目，能夠在 D:\book\Import\apitest 看到編輯器已自動生成好的項目文件

 

4.2 生成項目靜態網頁

命令行輸入：

gitbook build D:\book\Import\apitest

 

 等待執行結果，完成後能夠發現項目目錄已生成靜態網頁文件，點擊 D:\book\Import\apitest\_book\index.html，便可打開生成好的網頁文件

 

 

4.3 運行WEB服務

命令行輸入：

gitbook serve D:\book\Import\apitest

 

當命令行顯示以下字符時，表示項目WEB服務已開啓

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

瀏覽器輸入：http://localhost:4000，便可直接打開項目靜態網頁