Sync a Note with GitHub

中文教學

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

How to Sync a Note

You can sync your note from the editor of an empty note, or from the Versions and GitHub Sync panel.

The free plan can be used 20 times per month, upgrade to the HackMD Prime plan for unlimited pushes and pulls.

Choose the version you want to Push or Pull.

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.

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.

Hint: Install HackMD GitHub App on GitHub

---

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.

Note: You will most likely be asked to switch your line break rendering rules in this step. Learn more about line break rendering rules.

ℹ️ 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 Versions and GitHub Sync panel. You can always push further changes to, pull from, or unlink the note from GitHub in the Versions and GitHub Sync panel.

Add GitHub badge

After linking the note, you can add a badge to the top of the note by clicking the Add badge button in the Versions and GitHub Sync 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.

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.

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.

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: Click here

If you ever want to un-install the app for your personal repos, find it here: Click here

For un-installing your organization repos, find it here, you obviously need adequate permissions: Click here

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 (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 Enter (or Return) 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 in the Spec.

Soft line breaks

There's another way to render the "newline" character: the soft line break (or just line break). The newline character will be rendered as a Space 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 Space Space Enter
bar

2. Type a backslash at the end of the line, before the newline character:

foo \ Enter
bar

Hint

• Line breaks take effect only within the containing paragraph. If you want to start a new paragraph, just hit Enter (or Return) twice.
• 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.】

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 settings.
2. You can click the Breaks button at the bottom of the editor to choose your line break rendering rule.