中文教學

How to Sync a Note

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

【New

Image Not Showing Possible Reasons

• The image file may be corrupted
• The server hosting the image is unavailable
• The image path is incorrect
• The image format is not supported

Learn More →

】Copy Version Link

Now you can directly copy the saved version of a record.

There is a copy link button on the top right, click it to copy the version link and share it with others. As long as the other person has read access, they can view it.

Build connection with GitHub repo

You can sync your note from the editor of an empty note, or from the Versions and GitHub Sync panel. Then, 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.

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.

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.

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.

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.

Install the App on More Repos

If you cannot find the repo you want to link to, cancel the synchronization first.

Then, you can re-authorize the app on more 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

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

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.