輸出目標文件
語法格式: 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 服務器做靜態資源服務器等.
畢竟,源碼和輸出內容都在你手中,想怎么玩還不是自己說了算?