---
tags: tutorials
disqus: hackmd
---

{%hackmd KghC_AJ7Rui37eDW5PVl9Q %}

Sync a Note with GitHub
===
[**中文教學**](/c/tutorials-tw/%2Fs%2Flink-with-github-tw)

You can link a HackMD note with a Markdown file on GitHub to keep all your documentation in sync.

:::success
[Try HackMD Prime Personal, first month is on us](https://hackmd.io/@hackmd-marketing/Prime_Personal_english)
:::

## How to Sync a Note
You can sync your note from the editor of an empty note, or from the <i class="fa fa-history fa-fw"></i> **Versions** panel.


## Authorize HackMD on GitHub
On your first time linking HackMD with GitHub, you will be asked to authorize HackMD GitHub App to access your GitHub account AND the repos you want HackMD to link to. There are two levels of authorization needed: the account and the repositories.

:::info
:warning: HackMD cannot verify users through GitHub APP due to its limitations. So please connect to GitHub with the account that has Admin permission to the repo. For a team's notes, *team admin*, *team member* and *invitee admin* permissions will do.
:::

### 1. Account Level Authorization
HackMD GitHub App needs your authorization to see the repos you have access to, including your personal repos and those of Organizations you belong to.

### 2. Repo Level Authorization (Installation)
Once you authorize the HackMD GitHub App to see which repos you have access to, GitHub would let you choose which repos you would authorize, or "install", the app on. Install on as many repos as you like, or come back later to authorize more repos.

:::info
:bulb: **Hint:** Install HackMD GitHub App [on GitHub](https://github.com/apps/hackmd-hub)
:::

---
## Link a Note for the First Time
On your first time pushing a note to or pulling a file from Github, you will choose which repo, branch, and file you want to link with the current HackMD note. You can also create a new target branch or file to push the note to by simply typing the name of the branch or file to create them.

:::warning
:warning: **Note**: You will most likely be asked to switch your line break rendering rules in this step. [Learn more about line break rendering rules](#Line-Break-Rendering-Rules).


:::

:::info

ℹ️ **Info**: You can sync and edit .md/.mdx/.rmd/.markdown files in HackMD. However, HackMD does not support rendering of MDX and R syntax.

:::

---

## Keep your note sync with GitHub
After you link the note, the target repo and file will show on the <i class="fa fa-history fa-fw"></i> **Versions** panel. You can always push further changes to, pull from, or unlink the note from GitHub in the <i class="fa fa-history fa-fw"></i> **Versions** panel.


### Add GitHub badge
After linking the note, you can add a badge to the top of the note by clicking the <i class="fa fa-link fa-18"></i> **Add badge** button in the <i class="fa fa-history fa-fw"></i> **Versions** panel. When pushed to GitHub, the badge shows your community where to participate the discussion or contribute to the documentation.


### Push to GitHub
You can choose which named versions to push to GitHub before the push. Each named version would be pushed as a "commit" in Git, while the version name and description will be used as its commit message.
[Learn How to Save a Version](/s/how-to-save).


:::info
:bulb: **Hint:** HackMD doesn't track which versions had been pushed, for this information would be misleading should someone else messes with the branch from GitHub, which HackMD could not know.
:::

### Pull from Github
You can also pull from GitHub and choose the branch you want to pull from. Moreover, you can choose which chunk of revisions to merge into your note, or apply all changes.


:::info
:bulb: **Hint:** HackMD will automatically save a version before you merge and name it `before pull from <branch_name>`. Because HackMD doesn't lock the note when applying changes, it is possible that someone else edit your note while you're merging, therefore, "undoing" the merge has to be done in the editor.
:::
---
## Install the App on More Repos
If you cannot find the repo you want to link to, authorize the app on more repos.

:::info
:bulb: **Hint:** Remember to refresh the repo list after you authorize new repos.
:::

## Revoke Authorization and Un-installation
If you ever want to revoke the account level authorization, this is where you would find the option: https://github.com/settings/apps/authorizations

If you ever want to un-install the app for your personal repos, find it here: https://github.com/settings/installations

For un-installing your organization repos, find it here, you obviously need adequate permissions:
https://github.com/organizations/your_organization_name/settings/installations

:::warning
:warning: **Note:** Note that your account authorization and repo installation are separated. You could have revoked the account authorization (and the app could no longer see what repos you have access to), yet keep the app installed on your repos (and you can still push to and pull from the repo).
:::

---
## Line Break Rendering Rules
HackMD follows the [CommonMark Spec](https://spec.commonmark.org/0.29/) (the Spec) to render Markdown syntax so your notes would be compatible with other platforms. Yet there's one thing HackMD handles slightly differently: line breaks.

### What are line breaks?
#### Hard line breaks
When you hit the <kbd>Enter</kbd> (or <kbd>Return</kbd>) key on your keyboard, you type a "newline" character. Since you most likely expect to start a new line, *HackMD* lets you continue on a new line (by rendering that "newline" character with a HTML break tag `<br />`). This rendering behavior is called [**hard line break**](https://spec.commonmark.org/0.29/#hard-line-breaks) in the Spec.


#### Soft line breaks
There's another way to render the "newline" character: the [**soft line break**](https://spec.commonmark.org/0.29/#soft-line-breaks) (or just line break). The newline character will be rendered as a <kbd>Space</kbd> in the HTML, instead of a new line. This is how **GitHub** and some other services handle line breaks.


Under this way, when you want to start on a new line (hard line break), you could:

**1. Type two or more spaces at the end of the line, before the newline character:**
> foo <kbd>Space</kbd> <kbd>Space</kbd> <kbd>Enter</kbd>
> bar


**2. Type a backslash at the end of the line, before the newline character:**
> foo <kbd>\ </kbd> <kbd>Enter</kbd>
> bar


:::info
:bulb: **Hint:** Line breaks take effect only within the containing paragraph. If you want to start a new paragraph, just hit <kbd>Enter</kbd> (or <kbd>Return</kbd>) twice.
:::

:::info
:bulb: **Hint:** Technically HackMD is compliant with the Spec, according to the Spec: ["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)
:::

### Should I care?
Since HackMD and GitHub renders line breaks differently, Your notes would look differently on the two platforms if the line break rendering rules are different. But if a note won't ever be pushed to GitHub, you don't have to worry about this.

### How do I change my line break rendering rule?

1. You can change your default line break rendering for all your future notes in your [<i class="fa fa-gear fa-fw"></i> **settings**](/settings).

2. You can click the <kbd>Breaks</kbd> button at the bottom of the editor to choose your line break rendering rule.


3. You can use the `breaks` YAML metadata to force switch the line break rendering - put the following at the very beginning of your note:

---
breaks: false  # False means NOT to render line breaks as hard line breaks.
---

[Learn more about YAML metadata](https://hackmd.io/yaml-metadata).

###### tags: `tutorial`