---
# System prepended metadata

title: 來打一套屬於 Markdown 的 Combo

---

先前有介紹過 Markdown 與 HackMD 一套 Combo 來管理自己的筆記和技術文件，可以說是從雲端為出發點，這次我們改從本地端開始並搭配版本控制讓整個架構更完整一點。

![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/1770305539000o5zucv.png)


## 這套流程架構試圖解決什麼問題？

當筆記不再只是「記在自己電腦裡」，  
而是希望做到：

- 用簡單、工具無關的方式長期紀錄（Markdown）

- 能回頭看歷史、知道改過什麼（版本控管）

- 有機會和其他人或整個 team 一起寫（協作）  或一起跨裝置的讀  （雲端） 

### 過往情境

以往的工作流程(Flow)比較像是每個人Keyin專屬於自己的那一份本地檔案(Local File)，寫好後再來開會或是由一個人整合成最終版本。溝通和版本管理成本比較高，很難確定每個人在來來回回幾次後所編輯的版本是不是都是一致的，也很難透過簡短的時間確認到底內容哪些部分有衝突。

而在編輯文檔時也很容易因為格式不同或是應用程式版本不同而造成版本整合差異。

於是我們可以嘗試把 **Markdown** + **Git** 流程給加進來。

### Markdown是什麼

Markdown 是一種輕量級標記語言，以純文字書寫，轉譯後可呈現格式化排版：「讓人寫得輕鬆，讓機器讀得清楚，讓格式保持一致」。

不需要特別去記該怎麼使用 Markdown 語法，很多工具都有提供 Markdown 語法套用的快捷按鍵，我們只需要知道 Markdown 的概念即可。
### Git是什麼

**Git 就是一套「有時間軸、可回溯、可多人同時作業的檔案管理與修改紀錄系統」。**  
它可以讓團隊知道「誰在什麼時候改了什麼」，改錯了也能退回來，大家不會互相覆蓋彼此的工作。

### 合體 - Markdown + Git

使用 Markdown 作為文件或筆記編寫，可以避免一般編寫媒介間版本所帶來的格式或排版問題。
再加上 Git 最擅長的文字內容版本控管，他能清楚且精準地指出 Markdown 內的內容哪一段被改或是和別人的版本有所衝突。

於是我們就能擁有一個很完整清晰的流程： Git 成為了我們從本地端(Local)連接各個目的地間的橋樑，用各種自己習慣的方式編輯 Markdown ，最後在安全也不跑版和蓋版的情況下釋出版本。

### 這個流程的痛點是什麼？

最大的問題就是不夠無腦，你沒有辦法一被召喚到戰場就立即和別人展開戰鬥，要先走到鐵匠鋪把需要的武器組裝和搭載才能成為強大的戰士。

## 讓我們從被召喚開始，踏上征途吧

在接下來的比喻中，怕你對太多工具的名詞產生角色混淆，給你一點指南：

- **你（使用者）**：寫筆記、整理想法的人

- **Markdown**：你實際寫下內容的文字方式

- **Obsidian**：你使用的筆記本與整理工具

- **emo** ：Obsidian的武器，安裝在 Obsidian 上的圖片外掛

- **Git** ：版本管控的門神和載運檔案的坐騎

- **GitHub**：存放與管理這些筆記/圖片的雲端倉庫

- **HackMD**：讓其他人可以一起閱讀與編輯的共享空間


## 首先：名字可以自己取欸

Markdown 編譯的媒介百百種，即便你用 Windows 內建最陽春的`記事本`也沒關係，就算你不使用任何 Markdown 語法也無所謂。

但為了讓大家瞭解其他的編譯工具可以如何在流程上幫自己加速，這邊我就舉自己使用的工具──Obsidian 作為例子。之所以使用 Obsidian 最主要的原因就是他是一張可以畫上任何自己喜歡圖樣的白紙、一個沒有任何可愛磁鐵的冰箱門、一個沒有任何貼紙的筆電蓋或行李箱。

[你可以選擇這樣的一個名字 Obsidian](https://obsidian.md/)

![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/1767190569000ezrye6.png)

Obsidian 將你的所有筆記的儲存在本地端(Local)而且都是以 .md (Markdown)的方式來儲存。建立新的儲存庫即是選擇你要在本地端的哪一個資料夾作為筆記的儲存地。而我是將儲存庫保存在雲端硬碟上做簡單的雙重備份。

![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/17671907770006v2hvh.png)

儲存庫名稱即是你存放筆記的 **資料夾名稱**。

你可以依據不同的筆記專案個別建立不同的儲存庫，不同儲存庫間是不共享外掛(Plugin)的。

![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/1767198635000jp9gld.png)

左側可以一覽你在儲存庫內的所有筆記。右側則可以很彈性的顯示筆記內的大綱或是關聯圖等等。

在套用外掛(Plugin)前 Obsidian 並沒有太複雜的功能，中間為主要的編輯區域，以 Markdown 語法為主要的標記方式。

若你想深入了解 Obsidian 的強大或是 Markdown 語法的玄妙，這邊也提供幾個參考。

[Obsidian 使用教學](https://medium.com/pm%E7%9A%84%E7%94%9F%E7%94%A2%E5%8A%9B%E5%B7%A5%E5%85%B7%E7%AE%B1/obsidian-%E4%BD%BF%E7%94%A8%E6%95%99%E5%AD%B8-%E7%B8%BD%E7%9B%AE%E9%8C%84-%E6%8C%81%E7%BA%8C%E6%9B%B4%E6%96%B0%E4%B8%AD-2d23dce3ef02)
[Markdown 入門速查表：給完全新手的收藏指南](https://vocus.cc/article/68efa7c1fd89780001a99c46)
### Obsidian 使用 Markdown 作為筆記最為煩人的缺點

這讓撰寫筆記和技術文件變得相對單純，不需要考慮字的顏色大小或格式且你在各個裝置上編輯也都是相同的方式。

但因為 Obsidian 是一款本地端(付費後可以雲端同步)的筆記軟體，在編輯文件是最麻煩的就是在上傳圖片的部分。若你只是在 Obisidian 的筆記內插入圖片，那圖片就只會存放在本地端，如果你將這份 Markdown 上傳或是自己進行雲端上的備份，圖片是不會跟著走的。

這讓習慣使用 $MS word 等文件編輯者在圖文並茂這件事從直覺變得有點彆扭。

當然，因為 Obisidian 本身就以彈性且多樣的外掛著名，我們也因此得以彌補這項致命的缺點。
## 第二：裝上武器

我們可以試著使用第三方外掛： [emo](obsidian://show-plugin?id=emo-uploader) 來協助我們完成在編輯文件或筆記的同時也把圖片快速的插入。

![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/1770298644000gwou2o.png)


emo 是協助你在貼上圖片時自動幫你將圖片上傳到雲端圖床然後取得圖片連結後直接轉換Markdown 語法插入筆記或文件的外掛。當本地端的圖片經上傳圖床並發布後他就成為了公開的圖片得以公開瀏覽，而也就是因為可以公開瀏覽圖片就真的可以和你的筆記/文件一起帶著走。

### 先幫武器找好倉庫
而在使用 emo 這個 plugin 之前，須先建立好自己的雲端圖床(放圖的地方)。我們以 GitHub 作為示範(Imgur 是比較簡單的選擇，但現在台灣 ip 在使用上會出現一點問題)。

除了以下我的說明外，你也可以參考作者的[中文版本說明](https://lestua.eu.org/notes/2022/10/16/172318/)

先建立一個 GitHub 帳號。之後點右上角自己的頭貼並進入 repositories 頁面。

按下New建立一個 repo(專案資料夾)。我們將會把上傳的圖片放在這個專案資料夾中。
![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/17702988910001brb13.png)


![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/1770299262000aubrxw.png)

幾個比較有關的設定

| 欄位                |                                 |
| ----------------- | ------------------------------- |
| Repositories name | 專案資料夾名稱                         |
| Description       | 專案敘述(可不填)                       |
| Choose visibility | Public 為公開專案(選) / Private 為私人專案 |

按下 Create repository 創建專案資料夾。點右上角自己的頭貼回到 repositories 頁面就可以看到你完成創建的專案資料夾了。

接下來我們要告訴 emo你已經找好圖的倉庫了，住址在哪裡──拿取 token。

![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/1770300555000jkvzdn.png)


點右上角自己的頭貼並進入 Settings 頁面，滑到最下面選擇左下角的 Developer settings。進入後選擇左邊的 Personal access token -> Tokens(classic)。或是你可以在有登入 GitHub 的情況下點 [Tokens page](https://github.com/settings/tokens) 連結直接到目的地。 

點選右上角的 generate new token(classic) 

![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/1770300850000srz2z9.png)

幾件要做的事情

| 欄位            |                                  |
| ------------- | -------------------------------- |
| Note          | 幫這個token取個名字                     |
| Expiration    | token的期限。若要長期使用請設定 No expiration |
| Select scopes | 把repo勾起來                         |
之後滑到最下面選擇 Generate token。

#### 這個時候

Token 已生成完成。請複製中間那一串亂碼。請確保完成複製，這串代碼不會再次顯示，沒複製到的話等等還要重新創一次 Token。

![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/1770301156000rwijcv.png)


回頭到 Obsidian 的 plugin 設定，將剛剛複製倒的 token 貼入 **令牌** 的欄位中，告訴 emo 這個 Plugin 貼好圖片後請透過這個 token 把圖片放在你剛剛建好的 GitHub repo 倉庫裡。

| 欄位    |                                    |
| ----- | ---------------------------------- |
| 使用者名稱 | 填你的 GitHub 使用者名稱                   |
| 儲存庫   | 填你剛剛創建好的專案名稱                       |
| 分支    | 若你只是照著剛剛的步驟做沒有額外創建Branches，這邊填main |
| 令牌    | 剛剛創建並複製好的 token 亂碼                 |
| 提交資訊  | 上傳圖片於 GitHub 上的敘述                  |


完成後可以隨便將一張圖片拖曳或從剪貼簿拉到 Obsidian 的文件內試試看。

![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/1770301554000einq4k.png)
上傳中會顯示這樣的提示，上傳成功就會直接看到圖片，之後貼上的圖片 emo 都會使用這個 token 幫你上傳到這個 repo 的資料夾內。

![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/1770301526000oqqhpb.png)


若你從 repo 移除圖片或是移除 repo ， Obsidian 文件內的圖片也會因為連結失效而跟著消失。

## 第三：拿好武器準備搭上名為 Git 的坐騎

在終於回到圖文並茂的起點之後，接下來我們需要透過 Git 來做到檔案的版本控制和傳輸，將完成好的檔案透過 Git 上傳到雲端。

而真正騎上 Git 前，我們需要好好準備一番。

### 東市買駿馬：安裝 Git
安裝 [Git](https://gitforwindows.org/)，全部都使用預設的選項即可。或是你可以照著[這個作者的步驟](https://github.com/doggy8088/Learn-Git-in-30-days/blob/master/zh-tw/02.md)來安裝

安裝完後在 windows 上執行 cmd(命令提示字元)。

輸入
```
git --version
```

若系統有回應你版本則代表你安裝成功。

### 西市買鞍韉：讓 Git 綁定 GitHub repo

到 GitHub 你要存放文件的 repo 點右上角的 `<> Code` 並複製 專案連結.git
![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/1770302736000py5tu7.png)

在 cmd 執行，先將你的位置指定到你要存放文件的本地資料夾 。
```
cd C:\Users\User\Documents
```
再執行 git clone 並把專案連結貼在後面。
```
git clone [專案連結]
```
如此 git 就會將這個 repo 從 GitHub 下載到你剛指定的本地資料夾中。

### 南市買轡頭：安裝 Git Plugin

這邊要留意，因為我們待會需要執行 Obsidian Plugin，所以需要將 Obsidian 儲存庫的路徑設定在剛剛 git clone 下來的位置(同個資料夾)。

在 Obsidian Plugin 中安裝 [Git(Plugin)](obsidian://show-plugin?id=obsidian-git)
![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/1770303275000ddnwea.png)

若你有將 Obsidian 儲存庫 與 版控資料夾(Git Clone)放在同一個地方，回到 Obsidian Git Plugin 設定的地方會呈現這個畫面。

![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/1770303399000vjtwxd.png)

但若設定有問題，則會呈現 `git plugin is not ready 

![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/1770303374000y092cl.png)

### 北市買長鞭：騎騎看
這時候已經接近打完收工了，先隨便在 Obsidian 的文件內塗塗改改

![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/17703038710006yof2g.png)

會發現右邊會提示你更改了哪些地方

![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/1770303895000cirnhl.png)

點下去會告訴你修改前與修改後。這樣一來就可以很清楚地協助自己瞭解你更改的文件版本狀況是如何。這就是 git 的魔力。

簡單說明一下上方的按鈕
![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/1770304040000d8mfqi.png)


| 按鈕  |                 |                                        |
| --- | --------------- | -------------------------------------- |
| 1   | Commit and sync | 將更改送到暫存區後並推送到 GitHub                   |
| 2   | Commit          | 將更改送到暫存區(commit 就像在專案時間軸上插一個「可回到的標記點」) |
| 3   | Push            | 將暫存區推送到 GitHub                         |
| 4   | Pull            | 從 GitHub 專案內下載                         |
| 5   | Refresh         | 更新更改狀況                                 |

我們之後就可以不用透過 cmd 去執行 Git，可以在 Obsidian 內 Pull 與 Push/Commit。

## 第四：中途到達 GitHub 轉運中心

在 Obsidian 完成文件更改之後，我們直接在 Plugin 按下 Commint and Sync 將檔案送進暫存區並推送。成功後會顯示訊息，我們也到 GitHub repo 倉庫上去確認一下版本是否更新成功。

![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/1770304370000dnjv0n.png)

看到版本敘述的日期更新就知道這是新的版本已上傳成功。

這樣一來我們就可以用 GitHub 作為版本管控，最終釋出的版本都以 GitHub 上 repo 內的檔案為最終版，要更改也以 GitHub 上的版本為基礎，先從 GitHub 把檔案 pull 下來再進行更改。

## 最後：轉乘通往世界

接著我們可以延伸運用，將最終版本的 GitHub 筆記/文件同步在 HackMD 上作為部落格文件發布或是外部團隊協作也或是透過 Web 架構方便在各裝置上預覽。

![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/1770304611000h00abo.png)

HackMD 提供了一份很好的中文說明，可以直接[進行參考](https://hackmd.io/c/tutorials-tw/%2Fs%2Flink-with-github-tw)

我們試著從 GitHub Pull 文件到 HackMD。
![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/1770304910000ptnxzu.png)

在`建立我的筆記這邊` 選擇 從 GitHub 匯入單檔。

![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/1770304977000yemajj.png)

若有完成同步步驟，在 `選擇Repo` 這邊就會顯示你的 GitHub 帳號內所擁有的 Repo。選擇文件所在的 Repo 和 Branch 最後文件會出現在 `選擇要同步的檔案` 中。再按下匯入，就可以成功將文件從 GitHub 抓過來。

![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/1770305165000c063ka.png)

HackMD 也會顯示文件的版本狀況。

退出後按右上角的分享，完成隱私設定後把連結散布出去，這樣這份文件也有一份線上發布的版本了。

若你只想作為可以提供線上閱覽的話，文件檔案放在 GitHub 上也可以直接分享，但 Github 對於非熟悉流程的作業者會有點距離感，HackMD 則提供一個相對較親民的UI，把他當成你自己的部落格吧。

之後若 GitHub 文件有更新，HackMD的發布版則需要回來`拉取變更` 。這樣線上的發布版本才會一致。

---

## 總結
我們回顧一下整個流程：
![gh](https://raw.githubusercontent.com/AzureRush/audiorookie/main/1770305539000o5zucv.png)

我們從本地端透過 Obsidian 用 Markdown 寫作，利用 emo + git 這兩個 Obsidian 的第三方掛件(Plugin) 透過 Git 進行版控到 GitHub 上，最後也同步一份到 HackMD 方便線上閱覽/修改。

**當然**，這整個流程也可以倒過來：在 HackMD 上用 Markdown 線上寫作後 Push 到 GitHub 並透過 Git 進行版控到本地端並用 Obsidian 搭配進行閱覽/修改。

這套流程並不是為了把筆記變得「更厲害」，而是讓紀錄這件事，能在時間拉長、事情變多、人開始加入之後，**依然不會失控**。

我選擇 Markdown、Git、以及後面的工具，並不是因為它們是唯一解答，而是因為它們讓「寫下來」這件事，可以慢慢從一個人進化為一個團隊、跨裝置都能一起跳下來使用的系統。