GitHub

About

• See Sync a Note with GitHub
  • Must have 1 push/pull in order for the option to show.
• Encourage collaboration: Add GitHub badge to the HackMD note.

Enable

1. Set up GitHub permissions.

• Make sure your HackMD email has GitHub access.
• GitHub account level email: Profile (Top-right button) > Settings > Emails > Add email address
• Or GitHub repository's permission settings: Team admin, Team member, or Invitee admin

2. Link GitHub to HackMD.

a. HackMD menu (Bottom-left button with username) > Settings > Integration > Select Link with GitHub.

b. HackMD Hub by HackMD would like permission to: … > Select Authorize HackMD Hub

• Error for a user without access: request to https://github.com/login/oauth/access_token failed, reason: read ECONNRESET

c. Manage GitHub Hackmd Hub app access.

3. Enable GitHub in a Note.

a. Note overflow menu (3 dots in the top-right) > Versions and GitHub Sync > Pull from GitHub or Push to GitHub > Select Authorize more repos

b. Install & Authorize HackMD Hub > For enhanced security only authorize HackMD access for Only select repositories vs. All repositories. > Select Install & Authorize

4. Change the GitHub .md file associated with a note.

a. Unlink: Note overflow menu (3 dots in the top-right) > Versions and GitHub Sync > GitHub Link Settings > Select Unlink.

b. Re-link to a new GitHub .md file.

Branches

• Create new branch from HackMD
  • New repositories without a main branch
  • New feature branch in an existing repositiory
• Sync with existing GitHub feature branches.
• Submit pull requests (PR) in GitHub to merge feature branches with the main and/or production branch(es).
• It can be useful to have a feature branch for each HackMD note.

Push

• Push to GitHub
• Each HackMD named version will push as a Git commit.
  • HackMD auto-saved versions will not produce commits.
• Commit message
  • Auto-generated based on the HackMD version name and description
  • Use a common commit message style guide.
• Select file
  • For HackMD books use a unique filename for the book index note.
    • Important when the book index note has the same title as the first note in the book, listed in the book's index.
    • E.g.
      • Book index note for this guide: hackmd-index.md
      • First note in the book: hackmd.md
  • Can push files within directories (folders), e.g. about/community-and-support.md
  • Filename format
    • Important for URLs, programmability, and command line compatibility
    • Use lowercase and separate words with hyphens - instead of spaces ( ) or camel casing (camelCasing).
    • Resources
      • Google developer documentation style guide
        • Filenames and file types
        • Capitalization
      • What technical reasons exist for not using space characters in file names? by superuser.com

Pull

• Pull from GitHub
• Can choose the branch to pull from
• Can choose the portion of pulled branch revisions to merge into the HackMD note

This is not technical advice. Always read the official documentation and do your own research.