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

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

選擇Create from template；接著選Pages/Gitbook -> Use template
取好名字、按Create Project、Visibility Level選成Public

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

5. 你的Gitbook就完成啦

2: 安裝GitKraken

基於初學者看到終端機可能會感到有點陌生，我們可以安裝GitKraken來輔助我們使用Git
我們選擇Start a hosted repo: on GitLab
照下圖的選擇 Clone : GitLab.com (這裡應該會要你登入你的GitLab帳號，登入後就會看到跟我一樣的畫面)；選擇你要clone的repo (我們選擇剛剛創的gitbook-demo)
同時要記得選擇取你的電腦上的位置(Full Path)我們目標就是把在GitLab上創好的Repo複製到我們自己的電腦裡。
這樣就完成啦；我們可以選Open Now
這樣就會看到我們的專案了
在Finder中也可以看到

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

3: 安裝Typora

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

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

4: 安裝VSCode

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

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

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

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

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

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

3: 打開Vscode，

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

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

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

這是我目前個人的配置，在"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: 打開終端機

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

更多終端機教學請看這裡

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

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

第三部分：如何編輯Gitbook

1: 新增文件

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

2: 編輯`SUMMARY.md`

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


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

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

3: push回gitlab

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

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

1: 如何Fork別人的文件

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

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

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