English version

點我

回到 HackMD 教學首頁

點我

給予建議 或回報BUG

如何與 GitHub 同步筆記

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

建立筆記連結

在同步筆記之前，您需要先建立筆記和 GitHub 檔案的連結。您可以直接在空白筆記的編輯器裡面找到連結的選項，或者到 版本 選單裡面進行操作。

免費方案每個月可以使用20次，升級到 Prime方案取得無限次數的推送和拉取。

授權 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。

小提示： 您也可以直接到 GitHub 上安裝 HackMD 的 GitHub App。

---

初次連結筆記

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

注意： HackMD 會請您切換您的換行規則，以和 GitHub 的換行規則保持一致。換行規則是甚麼？

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

---

和 Github 保持同步

在筆記建立連結以後，連結的存儲庫（repo）和檔案路徑就會出現在 版本與 GitHub 同步 選單上方。您也可以從這裡推送（push）您之前儲存過的筆記版本到 GitHub 上，或是 pull GitHub 上的更動。

嵌入 GitHub badge

在筆記建立連結以後，您可以點擊 版本與 GitHub 同步 選單上方的 嵌入 Badge 按鈕在筆記的上方嵌入 GitHub badge。透過這個 badge，您在 GitHub 上的社群就可以輕鬆地加入討論或是貢獻文件。

推送 (Push) 版本到 GitHub

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

相關：如何儲存版本？

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

從 GitHub 拉取 (Pull) 版本

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

小提示： 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

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

---

換行顯示規則

HackMD 遵循 CommonMark 標準 (標準) 所規定的Markdown 語法，所以你的筆記才可以和其他平台的 Markdown 相容。但是 HackMD 在換行規則的處理上和 GitHub 有一點不同

甚麼是換行規則？

硬換行

當你在編輯器裡面敲入 Enter (或是 Return) 的時候，你實際上是輸入了一個 "換行符號"

一般來說，敲入這個符號的動機通常是想要從新的一行開始繼續輸入，所以 HackMD 也就直接幫你換一個新行（將 "換行符號" 顯示為 HTML 的 <br />）。這種作法在 標準 裡被稱為 硬換行。

軟換行

相對的，"換行符號" 還有另外一種處理方式（在 標準 裡稱為軟換行），你敲入的 "換行符號" 在編輯器裡面會看到文字確實換了新行，但是在 HTML 的顯示上則只顯示了一個 空白鍵 。這是 GitHub 對 "換行符號" 的處理方法

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

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

第一行 Space Space Enter
第二行

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

第一行 \ Enter
第二行

小提示

• 換行規則的不同只對換行有影響，但不影響 HTML 的 "段落" （<p> </p>）如果你想要開始一個新段落，直接輸入Enter (或是 Return) 兩次即可。
• HackMD 的處理其實也是遵守 標準 的。在 標準 裡面允許：將軟換行視為硬換行來處理。（"A renderer may also provide an option to render soft line breaks as hard line breaks."）

換行規則和我有關嗎？

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

我要如何切換換行規則呢？

1. 你可以在 設定 裡面調整所有 "未來新增的筆記" 的換行規則。
2. 你可以在編輯器下方的 換行 按鈕裡面切換換行規則。