在 GitLab 建立 GitBook

日期：
在 GitLab 建立 GitBook

在整理自己的學習資料的時候興起了
「如果把我部落格中相同主題的內容做成一本書會不會比較方便呢？」

這個問題，說幹就幹
當然先說說為什麼會有這個想法吧
在我查找資料的時候，常常會看到前主管 KeJyun 所做的各種 GitBook
沒錯就是這麼簡單的原因

當然也有一部分是因為在第 11 屆鐵人賽之後
漸漸的把學習筆記用 Markdown 書寫
而不是用網誌提供的編輯器把資源綁定在特定平台上
文章內文複製貼上倒不是什麼大問題，比較大的問題在圖片等等內嵌資源
我換個平台就會吃滿叉燒包（現在還有這種說法嗎？）
所以我就得另外找地方放那些檔案，現是使用 imgur 服務
但是莫忘 flickr 當年的政策轉變，用 imgur 也可能會有類似的風險
而且圖片開始越來越多之後，就不知道哪張圖是在哪一篇用的了

最後還是把歪腦筋動到了 GitBook 上面

  • markdown 語法
  • 資源可以塞在同一個版本庫裡，不會雜亂無章
  • 免費！
  • 不用自己維護
  • 魔術大空間，資源存放的空間無限
  • 因為都是公開專案，所以書本數量也是無限的

決定好了之後就是開工
對於原本就在 GitHub 上把自己的履歷表部署成靜態網站的我，應該不難吧？
正當我研究怎麼部署時，我看到這篇：
淺談新版 GitBook（GitBook V2） —— 失去交流開放精神的企業導向產品

GitBook V2

  • 帳號體系不互通
  • 編輯器不支援原生 Markdown 寫作
  • 不再使用 Git Repositories 作為核心版本控制系統

還好當初曾經，在前公司有想過要做內部 GitBook
因為前公司使用的是 GitLab，最後為什麼沒做就是另外的故事了
抱著一絲絲期望，果然在 GitLab 上找到了 GitBook 這個專案

然後就是這麼突然！我來一步步說明怎麼在 GitLab 建立 GitBook

建立專案

沒錯就是建立一個空白的 Project，就是這麼簡單
把 Visibility 改成 Public 大家才看得到
至於 README 要不要建立都可以

設定 CI/CD

這大概是最難的一個步驟了
照個官方文件在專案中新建一個檔案 .gitlab-ci.yml
把內容全部貼上之後應該就會自己執行部屬
而在執行之後驚喜來了

Error loading version latest: Error: Cannot find module 'internal/util/types'
  at Function.Module._resolveFilename (module.js:538:15)
  at Function.Module._load (module.js:468:25)
  at Module.require (module.js:587:17)
  at require (internal/module.js:11:18)
  at evalmachine.<anonymous>:31:26
  at Object.<anonymous> (/root/.gitbook/versions/2.6.9/node_modules/graceful-fs/fs.js:11:1)
  at Module._compile (module.js:643:30)
  at Object.Module._extensions..js (module.js:654:10)
  at Module.load (module.js:556:32)
  at tryModuleLoad (module.js:499:12)
  TypeError: Cannot read property 'commands' of null
  ERROR: Job failed: exit code 1

而我一開始的除錯方法，就是複製這段去問 Google
得到的是 node 版本如果降到 v6.12.3 就可以了
我實際測試也是可以，但是我覺得事情不是這樣運作的
畢竟 GitBook 官方也有在更新他們的 GitBook，不可能沒遇到一樣的問題

等等！你是說 GitBook 有在更新他們的 GitBook？
於是我就點開了 GitBook 自己的 .gitlab-ci.yml

# requiring the environment of NodeJS 10
image: node:10
# add 'node_modules' to cache for speeding up builds
cache:
 paths:
 - node_modules/ # Node modules and dependencies
before_script:
 - npm install gitbook-cli -g # install gitbook
 - gitbook fetch 3.2.3 # fetch final stable version
 - gitbook install # add any requested plugins in book.json
test:
 stage: test
 script:
 - gitbook build . public # build to public path
 only:
 - branches # this job will affect every branch except 'master'
 except:
 - master
  
# the 'pages' job will deploy and build your site to the 'public' path
pages:
 stage: deploy
 script:
 - gitbook build . public # build to public path
 artifacts:
 paths:
 - public
 expire_in: 1 week
 only:
 - master # this job will affect only the 'master' branch

原來他們加上了測試，並且把 node 版本升級到了 10
而不是 README 中的 8.9，坑啊！
於是我提交了 Merge Request，算是第一次參與開源專案

升到了 10 之後一切 CI 運行正常
如果不正常的同學 請去看醫生，並注意個人衛生
就想辦法改到他正常了才可以往下進行

撰寫書本內容

GitBook 由兩個部分組成

  1. 大綱
  2. 內文

大綱

SUMMARY.md 是 GitBook 的摘要，也就是閱讀模式中左側的各個頁面連結
要做的事情就是在內文寫好之後，在這邊加入連結

作為範例，先創建一個 SUMMARY.md 並輸入以下內容

# Summary

* [Introduction](README.md)

可以看到我們設定了一個連結 Introduction 連結網址是 README.md

內文

剛剛在大綱設定了 Introduction 這個標題點下去，要連到 README.md 這篇文章
所以我們也就新建一個 README.md
至於這隻檔案的內容就隨便亂打一些東西吧

發布

每當有檔案被 commit，我們的 CI 都應該自動開始部署
所以才會說要在 CI/CD 設定好之後再往下進行

若一切正常，則在工具列點選「Setting」→「Pages」
應該就可以得到專案文件也就是我們的 GitBook 的靜態網址
一般預設是
https://username.gitlab.io/project-name
非常感人的也幫我們做好了 https，真開心

而若是第一次發布，系統也在下方貼心的提示
It may take up to 30 minutes before the site is available after the first deployment.
所以不要這麼心急的去刷新頁面，可以去洗個澡或是吃個飯
等一陣子之後再回來試試，屆時你的 GitBook 應該就正常可以閱讀啦！

以上就是在 在 GitLab 建立 GitBook 的方法

留言

張貼留言