Gitbook 教學 2020.03 (by 林協霆)

tags: tutorials

前言

在各科實習總是會有各科的survivial guide，最近發現雙和醫院沈士強醫師製作的一般外科工作手冊，以gitbook呈現出精實好讀的內容，也想自己來實作。經過多方研究，發現以gitlab page呈現gitbook是最有效率，自由度也最高。在github上的gitbook在去年已經轉為收費模式，相當難用。以下內容包含如何在gitlab新增gitbook project、基本的git操作、用Gitkraken 的GUI介面降低對git的恐懼、如何Fork跟push，如果你只是一個協作者，可以直接跳到第四部分

第一部分：申請Gitlab、安裝Gitkraken、安裝Typora、安裝Atom

1: 申請Gitlab

1. 可以先了解一下什麼是Git。而Github或Gitlab，都是不錯代碼托管的大平台，而這兩家中，雖然Github一直都是龍頭，但Gitlab提供的page服務、以及gitbook template，讓我們可以快速地佈署我們的Gitbook，因此我們要先去申請一個Gitlab帳號
2. 我們可以點選右上角的New Project 來新增一個專案

3. 選擇Create from template；接著選Pages/Gitbook -> Use template
   

   
   

4. 取好名字、按Create Project、Visibility Level選成Public

注意名命時不要有空格，請用-代替

5. 你的Gitbook就完成啦

2: 安裝GitKraken

1. 基於初學者看到終端機可能會感到有點陌生，我們可以安裝GitKraken來輔助我們使用Git
   

2. 我們選擇Start a hosted repo: on GitLab
   

3. 照下圖的選擇 Clone : GitLab.com (這裡應該會要你登入你的GitLab帳號，登入後就會看到跟我一樣的畫面)；選擇你要clone的repo (我們選擇剛剛創的gitbook-demo)

4. 同時要記得選擇取你的電腦上的位置(Full Path)我們目標就是把在GitLab上創好的Repo複製到我們自己的電腦裡。
   

5. 這樣就完成啦；我們可以選Open Now
   

6. 這樣就會看到我們的專案了
   

7. 在Finder中也可以看到
   

當然如果你懂git的話，也可以直接在終端裡clone下來

3: 安裝Typora

1. 這是一個Markdown編輯器；用來編輯.md文件。可以參考這篇還有這篇；也可看看別人心得，介面大概如下圖所示

2. 我們可以在Finder中設定所有.md格式的文件都用Typora打開
   

4: 安裝VSCode

之後可能會用來編輯一些Code，

第二部分：如何設定自己的Gitbook

1: 到官網安裝Node.js，選擇Long Term Support (LTS) 版本

在mac中，我自己是用Homebrew安裝的，可以直接在終端機裡輸入 brew install node (要先裝好Homebrew，詳見這篇)

2: 回到我們的gitbook-demo檔案夾

1. 我們要做一些配置，詳細內容可以看這本Gitbook，如果懶得看就照下面的步驟來就可以。

3: 打開Vscode，

1. 在Start下選擇Open folder，打開我們的專案資料夾。
   
2. 新增一個名叫book.json的空白文件
   

或是直接在終端機裡輸入touch book.json

5. 接著把下面這段代碼貼入文件內，然後存檔

這是我目前個人的配置，在"plugines"中我設置了一些當用的插件，如果想要知道更多內容，可以看這裡。想要安裝更多插件，可以看這裡的教學

{
  "author": "作者",
  "description": "This is a sample book created by gitbook",
  "extension": null,
  "generator": "site",
  "links": {
    "sidebar":{
      "你的部落格" : "https://medium.com/as-a-med-student"
    }
  },

  "language": "zh",
  "plugins": [
        "-lunr",
        "-search",
        "search-pro",
        "chapter-fold",
        "expandable-chapters",
        "splitter",
        "back-to-top-button",
        "hide-element",
        "chapter-numbering",
        "code",
        "popup",
        "youtubex",
        "click-reveal",
        "auto-scroll-table",
        "pageview-count",
        "todo",
        "ancre-navigation",
        "flexible-alerts",
        "js-sequence-diagram-full@>=0.3.1",
        "mermaid"
      ],
  "pluginsConfig": {
    "hide-element": {
        "elements": [".gitbook-link"]
    }
  }
}

4: 打開終端機

2. 在mac中，把我們的檔案夾拉到dock中的終端機圖示上放開
   
3. 應該會看到如下的圖片
   

更多終端機教學請看這裡

4. 在終端機裡輸入gitbook install安裝plugin
   
5. 在終端機裡輸入gitbook serve發佈這本書
   

5: 完成，在Chrome中貼上http://localhost:4000就可以開啟書了

第三部分：如何編輯Gitbook

1: 新增文件

1. 點開README.md檔案來開啟typora，在左側側邊欄會看到這個資料夾下的所有檔案
   
2. 按左下角有一個+號，新增一個叫chapter1的文件
   
3. 在這裡我們就可以開始用Markdown語法來編輯文件了

2: 編輯SUMMARY.md

1. 我們還要把這個文件加入我們的目錄中，請打開SUMMARY.md, 並依照項目符號加入檔案，好了之後存檔

-[顯示名稱](檔名.md)
-[顯示名稱](子資料夾/檔名.md)

2. 我們可以在終端機中執行gitbook serve指令，看一下我們的成果，一樣到http://localhost:4000 ，就可以看到我們新增的第一章了

3: push回gitlab

1. 打開Gitkraken，選擇右上角View changes
   
2. 接著選 Stage all changes
   
3. 在下面的Commit Message中打入我們做的調整 (提醒自己做了哪些事)；接著按 Commit
   
4. 然後按Push上傳我們的更動回GitLab
   
5. 完成
   
6. 接著我們回到GitLab，可以在左欄 Repository下的 Commits中，看到我們剛剛推送的 Commit，可以看到Status的小logo顯示正在運行中
   
7. 完成就會在CI/CD下的Pipelines看到Commit顯示為 passed
   
8. 在左側找到Settings: Pages，可以看到Your pages are served under : e.g. https://htlin222.gitlab.io/gitbook-demo
   
9. 我們的書就大功告成了
   

第四部分：如何Fork別人的Gitbook，並協作

1: 如何Fork別人的文件

在這篇裡提到：在 GitHub 上有個有趣的機制：

1. 先複製（Fork）一份原作的專案到你自己的 GitHub 帳號底下。
2. 因為這個複製回來的專案已經在你自己的 GitHub 帳號下，所以你就有完整的權限，想怎麼改就怎麼改。
3. 改完後，先推回（Push）你自己帳號的專案。
4. 然後發個通知，讓原作者知道你有幫忙做了一些事情，請他看一下。
5. 原作者看完後說「我覺得可以」，然後就決定把你做的這些修改合併（Merge）到他的專案裡。

其中，第 4 步的那個「通知」，就是發一個請原作來拉回去（Pull）的請求（Request），稱之 Pull Request，簡稱 PR。

1. 辦好Gitlab後，當你開啟別人的專案(你可以點我的試試看)，請點右上角的fork
   
2. 可以看到這個project已經成功複製到你自己的頁面來了
   
3. 接下來你可以自行修改這個專案內容，你可以clone到自己電腦裡，也可以增加.md的文件後，照上面教過的push功能從本地推到雲端
4. 你也可以直接上傳.md文件
   
5. 如果你用不習慣typora，也可以直接在hackMD裡編輯後，在右上角的選單中下載成markdown (.md)格式，然後用上一個步驟的方式上傳
   
6. 可以直接在GitLab裡修改SUMMARY.md，選擇右上角的 edit
   
7. 記得commit
   

2: 如何把內容推回去給原作者

1. 在左欄有一個叫Merge Requests的選項 (GitHub叫Pull request)，選擇new merge request
   
2. 選擇你自己要Merge的sourse branch，接著按Compare branches and continue
   
3. 可以描述一下你做了哪些更動
   
4. 捲到最底submit merge request
   
5. 原作者就會在自己的repo中看到來自你的merge request
   
6. 他只需要按Approve，再按Merge就可以了

7. 再回到 https://htlin222.gitlab.io/gitbook-demo 看看，可以見到我們的更動都在了~

結語

製作好看的共筆一直時自學生時間以來所追求的聖杯，如果共筆組以HackMD一起製作共筆，完成後下載成.md，再由共筆長編入Gitbook，相信在製作發行上，一定會更有效率。