轉

gitbook使用教程

 

通過NPM安裝

安裝 GitBook 的最好辦法是通過 NPM。在終端提示符下，只需運行以下命令即可安裝 GitBook：

$ npm install gitbook-cli -g

 

gitbook-cli 是 GitBook 的一個命令行工具。它將自動安裝所需版本的 GitBook 來構建一本書。

執行下面的命令，查看 GitBook 版本，以驗證安裝成功。

$ gitbook -V

 

安裝歷史版本

gitbook-cli 可以輕松下載並安裝其他版本的GitBook來測試您的書籍：

$ gitbook fetch beta

 

使用 gitbook ls-remote 會列舉可以下載的版本。

創建一本書

初始化

GitBook可以設置一個樣板書：

$ gitbook init

 

如果您希望將書籍創建到一個新目錄中，可以通過運行 gitbook init ./directory 這樣做。

構建

使用下面的命令，會在項目的目錄下生成一個 _book 目錄，里面的內容為靜態站點的資源文件：

$ gitbook build

 

Debugging

您可以使用選項 --log=debug 和 --debug 來獲取更好的錯誤消息（使用堆棧跟蹤）。例如：

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

 

啟動服務

使用下列命令會運行一個 web 服務, 通過 http://localhost:4000/ 可以預覽書籍

$ gitbook serve

 

GitBook 命令

這里主要介紹一下 GitBook 的命令行工具 gitbook-cli 的一些命令, 首先說明兩點:

• gitbook-cli 和 gitbook 是兩個軟件
• gitbook-cli 會將下載的 gitbook 的不同版本放到 ~/.gitbook中, 可以通過設置GITBOOK_DIR環境變量來指定另外的文件夾

列出 gitbook 所有的命令

gitbook help

 

輸出 gitbook-cli 的幫助信息

gitbook --help

 

生成靜態網頁

gitbook build

 

生成靜態網頁並運行服務器

gitbook serve

 

生成時指定gitbook的版本, 本地沒有會先下載

gitbook build --gitbook=2.0.1

 

列出本地所有的gitbook版本

gitbook ls

 

列出遠程可用的gitbook版本

gitbook ls-remote

 

安裝對應的gitbook版本

gitbook fetch 標簽/版本號

 

更新到gitbook的最新版本

gitbook update

 

卸載對應的gitbook版本

gitbook uninstall 2.0.1

 

指定log的級別

gitbook build --log=debug

 

輸出錯誤信息

gitbook builid --debug

 

Gitbook 目錄結構

GitBook 項目結構

GitBook使用簡單的目錄結構。在 SUMMARY （即 SUMMARY.md 文件）中列出的所有 Markdown / Asciidoc 文件將被轉換為 HTML。多語言書籍結構略有不同。

一個基本的 GitBook 電子書結構通常如下：

├── book.json
 
├── README.md
 
├── SUMMARY.md
 
├── chapter-1/
 
| ├── README.md
 
| └── something.md
 
└── chapter-2/
 
├── README.md
 
└── something.md

　　

GitBook 特殊文件的功能：

 

文件	描述
book.json	配置數據 (optional)
README.md	電子書的前言或簡介 (required)
SUMMARY.md	電子書目錄 (optional)
GLOSSARY.md	詞匯/注釋術語列表 (optional)

靜態文件和圖片

靜態文件是在 SUMMARY.md 中未列出的文件。除非被忽略，否則所有靜態文件都將復制到輸出路徑。

忽略文件和文件夾

GitBook將讀取 .gitignore，.bookignore 和 .ignore 文件，以獲取要過濾的文件和文件夾。這些文件中的格式遵循 .gitignore 的規則：

1. # This is a comment
    
   
    
   # Ignore the file test.md
    
   test.md
    
    
   
   # Ignore everything in the directory "bin"
    
   bin/*
   項目與子目錄集成

對於軟件項目，您可以使用子目錄（如 docs/ ）來存儲項目文檔的圖書。您可以配置根選項來指示 GitBook 可以找到該圖書文件的文件夾：

1. ├── book.json  5  
   └── docs/
    
   ├── README.md  9  
   └── SUMMARY.md

在 book.json 中配置以下內容：

1. {
    
   "root": "./docs"
    
   }

    

Summary

GitBook 使用 SUMMARY.md 文件來定義本書的章節和子章節的結構。 SUMMARY.md 文件用於生成本書的目錄。

SUMMARY.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)

 

 

 

每章都有一個專用頁面（part#/README.md），並分為子章節。

錨點

目錄中的章節可以使用錨點指向文件的特定部分。

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

 

部分

目錄可以分為以標題或水平線 ---- 分隔的部分：

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

 

Parts 只是章節組，沒有專用頁面，但根據主題，它將在導航中顯示。

頁面

Markdown 語法

默認情況下，GitBook 的大多數文件都使用 Markdown 語法。 GitBook 推薦使用這種語法。所使用的語法類似於 GitHub Flavored Markdown syntax 。

此外，你還可以選擇 AsciiDoc 語法。

頁面內容示例：

 

 
# Title of the chapter
 
 
 
This is a great introduction.
 
 
 
## Section 1
 
 
 
Markdown will dictates _most_ of your **book's structure**
 
 
 
## Section 2
 
 
 
...

 

 

 

頁面前言

頁面可以包含一個可選的前言。它可以用於定義頁面的描述。前面的事情必須是文件中的第一件事，必須采取在三虛線之間設置的有效YAML的形式。這是一個基本的例子：

 
---
 
description: This is a short description of my page
 
---
 
 
 
# The content of my page
 
...

 

Glossary

允許您指定要顯示為注釋的術語及其各自的定義。根據這些術語，GitBook 將自動構建索引並突出顯示這些術語。

GLOSSARY.md 的格式是 h2 標題的列表，以及描述段落：

1.  
   ## Term
2.  
   Definition for this term
3.  
    
4.  
   ## Another term
5.  
   With it 's definition, this can contain bold text
6.  
   and all other kinds of inline markup ...

Gitbook 配置

GitBook 允許您使用靈活的配置自定義您的電子書。

這些選項在 book.json 文件中指定。對於不熟悉 JSON 語法的作者，您可以使用 JSONlint 等工具驗證語法。

常規設置

變量	描述
root	包含所有圖書文件的根文件夾的路徑，除了 book.json
structure	指定自述文件，摘要，詞匯表等的路徑，參考 Structure paragraph.
title	您的書名，默認值是從 README 中提取出來的。在 GitBook.com 上，這個字段是預填的。
description	您的書籍的描述，默認值是從 README 中提取出來的。在 GitBook.com 上，這個字段是預填的。
author	作者名。在GitBook.com上，這個字段是預填的。
isbn	國際標准書號 ISBN
language	本書的語言類型 —— ISO code 。默認值是 en
direction	文本閱讀順序。可以是 rtl （從右向左）或 ltr （從左向右），默認值依賴於 language 的值。
gitbook	應該使用的GitBook版本。使用 SemVer 規范，並接受類似於 “> = 3.0.0” 的條件。

author

作者姓名，在GitBook.com上，這個字段是預先填寫的。

例：

"author" : "victorzhang"

 

description

電子書的描述，默認值是從 README 中提取出來的。在GitBook.com上，這個字段是預先填寫的。

例：

"description" : "Gitbook教程"

 

direction

文本的方向。可以是 rtl 或 ltr，默認值取決於語言的值。

例：

"direction" : "ltr"

 

gitbook

應該使用的GitBook版本。使用SemVer規范，接受類似於 >=3.0.0 的條件。

例：

1.  
   "gitbook" : "3.0.0",
2.  
   "gitbook" : ">=3.0.0"

language

Gitbook使用的語言, 版本2.6.4中可選的語言如下：

en, ar, bn, cs, de, en, es, fa, fi, fr, he, it, ja, ko, no, pl, pt, ro, ru, sv, uk, vi, zh-hans, zh-tw

 

例：

"language" : "zh-hans",

 

links

在左側導航欄添加鏈接信息

例：

1.  
   "links" : {
2.  
   "sidebar" : {
3.  
   "Home" : "https://github.com/atlantis1024/gitbook-notes"
4.  
   }
5.  
   }

root

包含所有圖書文件的根文件夾的路徑， book.json 文件除外。

例：

"root" : "./docs",

 

structure

指定 Readme、Summary、Glossary 和 Languages 對應的文件名。

styles

自定義頁面樣式， 默認情況下各generator對應的css文件

例：

1.  
   "styles": {
2.  
   "website" : "styles/website.css" ,
3.  
   "ebook" : "styles/ebook.css" ,
4.  
   "pdf" : "styles/pdf.css" ,
5.  
   "mobi" : "styles/mobi.css" ,
6.  
   "epub" : "styles/epub.css"
7.  
   }

例如要使 h1、h2 標簽有下邊框， 可以在 website.css 中設置

1.  
   h1 , h2{
2.  
   border-bottom: 1px solid #EFEAEA;
3.  
   }

title

電子書的書名，默認值是從 README 中提取出來的。在 GitBook.com 上，這個字段是預先填寫的。

例：

"title" : "gitbook-notes",

 

plugins

插件及其配置在 book.json 中指定。有關詳細信息。

自 3.0.0 版本開始，GitBook 可以使用主題。有關詳細信息，請參閱  the theming section 。

變量	描述
plugins	要加載的插件列表
pluginsConfig	插件的配置

添加插件

1.  
   "plugins": [
2.  
   "splitter"
3.  
   ]

添加新插件之后需要運行 gitbook install 來安裝新的插件

去除自帶插件

Gitbook 默認帶有 5 個插件：

• highlight
• search
• sharing
• font-settings
• livereload

1.  
   "plugins": [
2.  
   "-search"
3.  
   ]

structure

除了 root 屬性之外，您可以指定 Readme，Summary，Glossary 和 Languages 的名稱（而不是使用默認名稱，如README.md）。這些文件必須在項目的根目錄下（或 root 的根目錄，如果你在 book.json 中配置了 root 屬性）。不接受的路徑，如：dir / MY_README.md。

變量	描述
structure.readme	Readme 文件名（默認值是  README.md ）
structure.summary	Summary 文件名（默認值是 SUMMARY.md ）
structure.glossary	Glossary 文件名（默認值是 GLOSSARY.md ）
structure.languages	Languages 文件名（默認值是 LANGS.md ）

pdf

可以使用 book.json 中的一組選項來定制PDF輸出：

Variable	Description
pdf.pageNumbers	將頁碼添加到每個頁面的底部（默認為 true）
pdf.fontSize	基本字體大小（默認是 12）
pdf.fontFamily	基本字體樣式（默認是 Arial）
pdf.paperSize	頁面尺寸，選項有： 'a0', 'a1', 'a2', 'a3', 'a4', 'a5', 'a6', 'b0', 'b1', 'b2', 'b3', 'b4', 'b5', 'b6', 'legal', 'letter' （默認值是 a4）
pdf.margin.top	上邊界（默認值是 56）
pdf.margin.bottom	下邊界（默認值是 56）
pdf.margin.right	右邊界（默認值是 62）
pdf.margin.left	左邊界（默認值是 62）

生成電子書

GitBook 可以生成一個網站，但也可以輸出內容作為電子書（ePub，Mobi，PDF）。

 
# Generate a PDF file
 
$ gitbook pdf ./ ./mybook.pdf
 
 
 
# Generate an ePub file
 
$ gitbook epub ./ ./mybook.epub
 
 
 
# Generate a Mobi file
 
$ gitbook mobi ./ ./mybook.mobi

 

安裝 ebook-convert

ebook-convert 可以用來生成電子書（epub，mobi，pdf）。

 

參考鏈接：

https://blog.csdn.net/myemail_sl/article/details/76273474