gitbook 入門教程之發佈電子書

輸出目標文件

語法格式: gitbook build [book] [output]

默認狀況下,gitbook 輸出方式是靜態網站,其實 gitbook 的輸出方式有三種: website, json,和 ebook.

只不過另外兩種不是很經常使用,更多狀況下咱們是使用靜態網頁搭建我的官網,或託管到第三方平臺,或部署到私有云服務器,但無論怎麼樣,仍是離不開生成這一步.

示例:

# 默認輸出格式: `website`
$ gitbook build --format=website

# 更改輸出格式: `json`
$ gitbook build --format=json

# 更改輸出格式: `ebook`
$ gitbook build --format=ebook

默認狀況下輸出目錄: _book/,整個項目的入口文件是: index.html

集成 github 網站

本教程的電子書源碼和輸出文件均託管到 github 網站,因此這裏介紹下如何利用 Github Pages 靜態網頁服務與 gitbook 進行集成.

什麼是 GitHub Pages ?

Github Pages 是 github 網站推出的一種免費的靜態網頁託管服務,適合搭建靜態的項目主頁或我的官網.

其中,網站項目的源碼直接託管在 github 倉庫中,當倉庫文件更新後,該倉庫所關聯的網站自動更新,從而實現了源碼與官網的聯動更新.

若是想了解更多詳情,請參考官網: https://pages.github.com/

怎麼作 GitHub Pages ?

每一個帳號有且只有一個主頁站點,但容許無限制多的項目站點.

啥是主頁站點,項目站點又是啥?

別急,讓我先舉個例子看一下最終效果.

假如用戶名: zhangsan 名下有四個公開倉庫,一個倉庫名叫作: zhangsan.github.io,另外三種分別是: project01,project02,project03 .

若是想要對外暴露上述四個倉庫做爲咱們的靜態網站,那麼最終效果就是下面這樣的.

• 主頁站點: https://zhangsan.github.io
• 項目01站點: https://zhangsan.github.io/project01
• 項目02站點: https://zhangsan.github.io/project02
• 項目03站點: https://zhangsan.github.io/project03

注意將 zhangsan 替換成本身的 github 用戶名,不然八成是打不開網站,除非真的有 zhangsan 這個用戶.

其實上述規則很好理解,github 網站做爲一個託管中心,有成千上萬的用戶在使用 github 而且每一個用戶的用戶名都是惟一而且不一樣的,所以 *.github.io 通配符域名恰好充當命名空間.

能夠預料的是,不只僅有 <username>.github.io 這種二級域名,說不定還有 api.github.io,docs.github.io 等等,畢竟只須要購買 *.github.io 通配符域名證書就能夠支持任意多的二級域名了,感謝 github 贈送咱們免費的 https 網站.

說到這裏,不得不吐槽下 gitbook 的命名空間策略了,gitbook 也有本身的電子書託管服務,但訪問地址是 <username>.gitbook.io/<namespace> .

很顯然,gitbook 沒有區分主頁站點和項目站點,至關於所有都是項目站點,缺乏主次之分.

閒言少敘,既然知道了輸入內容和輸出效果,那麼接下來的任務就是了解中間過程了,讓咱們一塊兒探討下怎麼發佈網站吧!

主頁站點

建立 <username>.github.io 公開倉庫

前往 https://github.com/ 網站建立名爲 <username>.github.io 的公開倉庫.

好比個人用戶名是: snowdreams1006 ,那麼個人主頁站點倉庫就是: snowdreams1006.github.io

建立首頁 index.html 文件

不論是在線直接建立 index.html 仍是克隆到本地建立 index.html ,最終的 <username>.github.io 倉庫必定要有 index.html 首頁文件.

示例:

# 克隆到本地
$ git clone https://github.com/username/username.github.io

# 切換到項目
$ cd username.github.io

# 建立 `index.html` 文件
$ echo "Hello World" > index.html

# 推送到遠程倉庫
$ git add --all
$ git commit -m "Initial commit"
$ git push -u origin master

訪問主頁站點 https://username.github.io

打開瀏覽器,輸入網址: https://username.github.io 訪問主頁站點,顯示的內容正是咱們剛剛提交的 index.html 文件內容.

若是沒有正常顯示,清除瀏覽器緩存強制刷新試試看!

項目站點

相比主頁站點來講,項目站點命名比較隨意了,做爲靜態網站不可或缺的文件仍然是 index.html.

建立首頁 index.html 文件

建立首頁文件並添加測試內容,方便待會在線訪問項目站點測試是否部署成功.

設置 GitHub Pages 選項

點擊倉庫首頁右上方設置(Settings)選項卡,往下翻到 GitHub Pages 選項,選擇源碼目錄,根據實際狀況選擇源碼來源於 master 分支仍是其餘分支或者docs/ 目錄.

方便起見,選擇第一個 master 分支便可,注意下面的主題和這一步的來源只能二者選其一,不然主題優先級更高!

訪問主頁站點 https://username.github.io/<repository>

打開瀏覽器,輸入網址: https://username.github.io/repository 訪問項目站點,顯示的內容正是咱們剛剛提交的 index.html 文件內容.

若是沒有正常顯示,清除瀏覽器緩存強制刷新試試看!

如何集成 gitbook ?

咱們已經知道 Github Pages 是提供靜態網站的免費託管,而 gitbook 默認生成的內容就是靜態網站,二者如何結合天然不用我多說了吧?

gitbook 默認輸出目錄 _book/ 包括了靜態網站所需的所有資源,其中就包括 index.html 首頁文件.

所以咱們只須要每次生成後將 _book/ 整個目錄複製到項目根目錄,那麼推送到遠程倉庫時天然就是輸出後靜態網站了啊!

示例:

# 生成靜態網站
$ gitbook build

# 複製到項目根目錄
$ cp -r _book/* .

# 添加到本地版本庫
$ git add .
$ git commit -m "publish"

# 推送到遠程倉庫
$ git push origin master

如今登陸 github 網站看一下靜態網站是否成功上傳以及訪問主頁站點或項目站點看一下最新內容是否成功渲染吧!

小結

本節咱們學習 gitbook 有三種輸出方式,其中默認的網頁輸出最爲經常使用.

除此以外,還講解了如何與 github pages 進行結合,從而實現源碼和網站的自動更新維護.

若是源碼沒有託管到 github 這種第三方服務商,你也能夠搭建本身的服務器,好比將 _book/ 目錄所有扔到 nginx 服務器作靜態資源服務器等.

畢竟,源碼和輸出內容都在你手中,想怎麼玩還不是本身說了算?