---
tags: tutorials
disqus: hackmd
---
如何與 GitHub 同步筆記
===

{%hackmd zfoEnYvRQZqKUpGoVsyDJw %}

[**English version**](/c/tutorials/%2Fs%2Flink-with-github)

您可以將筆記與 GitHub 上的 Markdown 文件同步，以確保您的文件在各個平台上都保持同步。

## 建立筆記連結
在同步筆記之前，您需要先建立筆記和 GitHub 檔案的連結。您可以直接在空白筆記的編輯器裡面找到連結的選項，或者到 <i class="fa fa-history fa-fw"></i> **版本** 選單裡面進行操作。



## 授權 HackMD 存取 GitHub
如果您是第一次同步 HackMD 筆記到 GitHub，GitHub 會要求您**授權 HackMD GitHub App 存取您的帳號** 和 **安裝 app 在 repo (專案)上**。總共有兩層授權喔！（個人帳號及您有存取權的 repo。）

### 1. 授權個人帳號
HackMD GitHub App 需要您的授權才能知道所有您有權讀取的 repo 有哪些：包含您個人的 repo 及您所屬 GitHub Organization 所擁有的 repo。

### 2. 授權 Repo（安裝 App 到 Repo）
在您授權個人帳號之後，GitHub 就會讓您選擇要在哪些 repo 上安裝 HackMD GitHub App。您也可以稍後再回來授權更多 repo。

:::info
:bulb: **小提示：** 您也可以直接[到 GitHub 上安裝](https://github.com/apps/hackmd-hub) HackMD 的 GitHub App。
:::

---
## 初次連結筆記
在您第一次推送 (push) HackMD 筆記或是拉取 (pull) GitHub 檔案的時候，您可以選擇要連結這篇筆記到哪個 repo、哪個 branch、哪份 Markdown 檔案。您也可以在連結的時候手動新增 branch 或是新增檔案。


:::warning
:warning: **注意：** HackMD 會請您切換您的換行規則，以和 GitHub 的換行規則保持一致。[換行規則是甚麼？](#換行顯示規則)

:::

:::info

ℹ️ **資訊**: 您可以將 .md/.mdx/.rmd/.markdown 同步到 HackMD。這些格式都能在 HackMD 正常編輯，不過 HackMD 不支援算繪 MDX 和 R 的語法。

:::

---
## 和 Github 保持同步
在筆記建立連結以後，連結的 repo 和檔案路徑就會出現在 <i class="fa fa-history fa-fw"></i> **版本** 選單上方。您也可以從這裡 push 您之前儲存過的筆記版本到 Github 上，或是 pull GitHub 上的更動。


### 嵌入 GitHub badge
在筆記建立連結以後，您可以點擊 <i class="fa fa-history fa-fw"></i>**版本** 選單上方的 <i class="fa fa-link fa-18"></i>**嵌入 Badge** 按鈕在筆記的上方嵌入 GitHub badge。透過這個 badge，您在 GitHub 上的社群就可以輕鬆地加入討論或是貢獻文件。


### 推送 (Push) 版本到 GitHub
您可以選擇要 push 哪些命名版本到 GitHub 上，每個命名版本都會被視為一個 commit，版本的名稱和描述則會被存為該 commit 的 commit message。在這個步驟中，您也可以重新選擇目標 branch。

[相關：如何儲存版本？](/s/how-to-save-tw)


:::info
:bulb: **小提示：** 如果有人在 GitHub 上調整 repo 裡的 branch 或是 commit，GitHub 是不會提供通知給 HackMD GitHub App 的，因此 HackMD 也不會紀錄您已經 push 過了哪些版本，以避免提供錯誤的資訊。
:::

### 從 GitHub 拉取 (Pull) 版本
您也可以從 GitHub 不同的 branch 上 pull 最新的版本下來， 並選擇要將套用哪些變更。


:::info
:bulb: **小提示：** HackMD 會在您 pull 之前先自動存檔一個名為 `before pull from <branch>` 的版本。由於 HackMD 不會在您 pull 的時候將筆記鎖住，此時可能仍會有人進行變更，因此如果想要復原匯入版本差異的動作，需要回到編輯器後，用 `ctrl + z` (或`cmd + z`) 來復原匯入。
:::

---
## 授權更多 Repo（安裝 App 到更多 Repo）
如果在連結筆記的時候找不到想要連結的 repo，您可以授權更多 repo。


## 取消授權及解除安裝
如前所述，授權分成兩層：帳號及 repo。如果您想要取消帳號的授權，您可以在這裡進行：
https://github.com/settings/apps/authorizations

如果您想要解除您個人 repo 上安裝的 HackMD GitHub App，可以在這裡找到選項：
https://github.com/settings/installations

如果您想要解除安裝在您所屬的 GitHub Organization 上 repo 的 app，可以在這裡找到：
https://github.com/organizations/your_organization_name/settings/installations

:::warning
:warning: **注意：** 由於帳號授權分成兩層，有可能發生：您解除個人帳號的授權（HackMD 就無法看見您可以使用哪些 repo），但若沒有解除 repo 上的安裝，您就仍然可以在 HackMD 上 push 或 pull 新的變更至有安裝HackMD GitHub App 的 repo。
:::

---
## 換行顯示規則
HackMD 遵循 [CommonMark 標準](https://spec.commonmark.org/0.29/) (**標準**) 所規定的Markdown 語法，所以您的筆記才可以和其他平台的 Markdown 相容。但是，HackMD 在換行規則的處理上和 GitHub 有一點不同。

### 甚麼是換行規則？
#### 硬換行
當您在編輯器裡面敲入 <kbd>Enter</kbd> (或是 <kbd>Return</kbd>) 的時候，您實際上是輸入了一個 "換行符號"。一般來說，敲入這個符號的動機通常是想要從新的一行開始繼續輸入，所以 HackMD 也就直接幫您換一個新行（將 "換行符號" 顯示為 HTML 的 `<br />`）。這種作法在 **標準** 裡被稱為 [**硬換行**](https://spec.commonmark.org/0.29/#hard-line-breaks)。


#### 軟換行
相對的，"換行符號" 還有另外一種處理方式（在 **標準** 裡稱為[軟換行](https://spec.commonmark.org/0.29/#soft-line-breaks)）。您敲入的 "換行符號" 在編輯器裡面會看到文字確實換了新行，但是在 HTML 的顯示上，則只顯示了一個 <kbd>空白鍵</kbd> 。這是 GitHub 對 "換行符號" 的處理方法。


在軟換行的處理方式下，當您想要在 HTML 裡面顯示換新行（將 "換行符號" 顯示為 HTML 的 `<br />`）的時候，您可以用以下兩種方式來表示：

**1. 在換行符號前輸入兩個空白鍵：**

> 第一行 <kbd>Space</kbd> <kbd>Space</kbd> <kbd>Enter</kbd>
> 第二行


**2. 在換行符號前輸入一個反斜線：**

> 第一行 <kbd>\ </kbd> <kbd>Enter</kbd>
> 第二行


:::info
:bulb: **小提示：** 換行規則的不同只對換行有影響，但不影響 HTML 的 "段落" （`<p> </p>`）如果您想要開始一個新段落，直接輸入<kbd>Enter</kbd> (或是 <kbd>Return</kbd>) 兩次即可。
:::

:::info
:bulb: **小提示：** HackMD 的處理其實也是遵守 **標準** 的。在 **標準** 裡面允許：將軟換行視為硬換行來處理。（["A renderer may also provide an option to render soft line breaks as hard line breaks."](https://spec.commonmark.org/0.29/#soft-line-breaks)）
:::

### 換行規則和我有關嗎？
因為 HackMD 和 GitHub 對換行規則的處理方式不同，如果您沒有切換筆記的換行規則、又將該篇筆記和 GitHub 同步的話，筆記在 GitHub 上會和在 HackMD 上看起來不太一樣。

### 我要如何切換換行規則呢？
1. 您可以在 [<i class="fa fa-gear fa-fw"></i> **設定**](/settings) 裡面調整所有 "未來新增的筆記" 的換行規則。

2. 您可以在編輯器下方的 <kbd>換行</kbd> 按鈕裡面切換換行規則。


3. 您可以用 YAML 來個別設定每篇筆記的換行規則。將以下這三行放在筆記的最前面（比標題還前面的第一行）。

---
breaks: false  # false 表示採用 "軟換行規則"，即 "換行符號" 不會換到新行。
---

[相關：更多 YAML 的用法](https://hackmd.io/yaml-metadata)。

###### tags: `tutorial`