在 Gitlab 平台簡單創建 GitBook 電子書的步驟

GitLab 提供了 gitbook儲庫 的範本,只要用戶 Fork 該專案,如此就可以建立屬於自己的 GitBook 文檔網站。不過這方式我不太喜歡,需要修改專案名稱等相關屬性,然後也要編輯「README.md」、「SUMMARY.md」內容,如此就會造成 commit 歷史紀錄一開始較為雜亂。 (雖然也可以清除,但又要額外的步驟。)

除了 Fork 的方式,其實也可以自己手動新增空白的專案,然後再針對 GitLab CI (Continuous Integration) 設定並加入執行的腳本內容即可。 (其實就是 gitbook 儲庫內的 .gitlab-ci.yml 內容)

整理下創建 GitBook 網站@GitLab 平台的步驟:

  1. 新增空白專案
    這應該不用說吧,與 GitHub 新增專案的方式幾乎是一樣。大概就是注意下儲庫的存取改為「Public」,然後預設新增一「README.md」檔案,該檔案也是 GitBook 所必要的檔案。

    新增 GitLab 空白專案

  2. 設定 CI/CD
    新增專案後在出現的主視窗內,點選「CI/CD」按鈕,即會出現預設檔名為「.gitlab-ci.yml」的編輯視窗,將 GitLab 所提供在 GitBook 儲庫內的「.gitlab-ci.yml」檔案內容複製並貼上,並點選「Commit Change」即可完成設定。

    設定 CI/CD

  3. 新增檔案「SUMMARY.md」
    這是 GitBook 唯二所需的檔案之一 (另一就是 README.md),未來就是在該檔案內編輯 GitBook 文件的目錄結構。現在簡單加入下述內容即可:

    # Summary
    
    * [Introduction](README.md)
    
  4. 檢視 CI 執行情形
    當新增上述檔案並點擊「Commit Change」後,GitLab CI 就會執行建置部屬的程序。在專案左側的工具列儀表板,點選「CI/CD」→「Jobs」,然後再點擊 Jobs 鍊結,即可出現 CI 執行紀錄,只要最後一行顯示 Job succeeded 就表示已正常完成建置部屬的工作。
    新增檔案「SUMMARY.md」
  5. 查看文件網頁的網址
    工具列點選「Setting」→「Pages」,就可以察知專案文檔的靜態網頁網址,預設一般為 https://username.gitlab.io/project-name

    檢視 CI 執行情形

    查看文件網頁的網址

初始基於 GitBook 範本所建立的 GitLab 儲庫就完成了。後續就是 Clone 回本機端,然後可以安裝 Node.js 再透過其安裝 gitbook-cli,這些參考 官方設定文件 就可以很容易的安裝與設定完成,之後就可以在本機端建置與預覽該專案文檔了。

文章導覽

   

發表迴響

你的電子郵件位址並不會被公開。 必要欄位標記為 *