📄 HackMD

hackmd.io

About

Use – Real-time collaboration powered by Markdown documentation.

Guide – HackMD Tutorial Book

Adoption

• Ethereum Foundation (EF)
  • Monthly EIPs Insights: hackmd.io/@poojaranjan/EthereumImprovementProposalsInsight
  • AllCoreDevs bi-weekly updates: hackmd.io/@timbeiko/acd
  • Private team: notes.ethereum.org
• ConsenSys
  • What’s New in Eth2 series: hackmd.io/@benjaminion
• DAOHaus: hackmd.io/@daohaus
• Vitalik Buterin
  • hackmd.io/@vbuterin
  • notes.ethereum.org/@vbuterin
• How I use HackMD in Open Source projects

Team

• Size
  • Small, fast, and effective team of 8.
  • Growing up to 15 in 2023 mostly in developers.
• Location
  • Based mostly in Taiwan with a presence in San Francisco.

Features

See Features

Editor

Web app

• Create a new page from the address bar: hackmd.io/new
• Near instant updates to the published version
• Keyboard shortcuts for HackMD
  • Auto-format links: Highlight the text in the editor and then paste the link from the clipboard.
• Spell check: Understanding Your Editor > 19. Spell Check by CodiMD
• Table builder UI in the toolbar
  • Create a table
  • Add and remove rows and columns
  • Set the text alignment
• Word and character counts
  • Bottom-right corner of the editor view
  • Click for word count
• Test HackMD's version of Markdown vs. generic Markdown: View the markdown code in Visual Studio Code (VS Code).
• Customize themes and styles with Markdown and save to a template.
• How to Use Template
  • Boost Productivity with Templates

Visual Studio Code (VS Code)

About

• HackMD integration with VS Code
• Great for offline work and while working in other code bases.

Setup

1. Install VS Code HackMD extension.
2. Create a HackMD Access Token: How to issue an API token

Features

• Edits made sync automatically.
  • Changes in HackMD app update in VS Code.
  • Saved changes in VS Code update in HackMD.
• Quickly save files locally.

Workflows

A. Edit in HackMD web app.

1. Save file locally in VS Code.
2. Push updates to GitHub.

B. Edit file locally in VS Code.

1. Save file locally in VS Code.
2. Push updates to GitHub.
3. Pull updates from GitHub to HackMD web app.

Resources

• GitHub: github.com/hackmdio/vscode-hackmd
• Guide: Visual Studio Code (VS Code)

Collaborate

Notes

• Make sure an email is set to receive share invites
  • Set an account email if your sign-in is through a third-party, e.g. GitHub, Twitter, Google, and etc.
  • Menu (Bottom-left button with username) > Settings > Email
• Share edit access with specific user(s): Share button (Top-right) > Note Permission > More (Comment, Invitee) > Invitee > Add user's email > Select Write or Admin.
  • Invite Others to a Private Note
  • Features > Permissions
• For Books you must share each Note with contributors.
• View shared notes: My Workspace (hackmd.io/?nav=overview) > Collaborative Notes (hackmd.io/?nav=collab)
• Live Host a Collaborative Session

Teams

• See Create and manage Team
• Team domain URL
  • The Public URL is the same format as personal usernames, e.g. hackmd.io/@teamname.
  • Must be different than personal account domain URL.
• Invite users from outside the team: Use the note share settings.
• Back up notes: Same download all option as a personal account under settings

Publish

Custom links

• HackMD readable custom URLs
  • Format: hackmd.io/[@username]/[pagename]
  • How to Publish a Note with Permalink
• Custom domains with enterprise: hackmd.io/pricing
• Open a link in a new tab
  • Universal method
  • HackMD method: External link

Set metadata

• About
  • Sets the information that shows in the browser window/tab and link preview.
  • Supported YAML metadata
• Attributes
  • Title
  • Description
  • Tags
    • Helps organize the page
    • Tagging notes
  • Image
  • etc.

Title

• Automatically sets the title in the published version based on the metadata
• Disable: In any form of edit mode select Note settings ("i" button at the top menu bar, next to the note title)
  • Show title in view mode
  • Show tags in view mode

Formats

Books

• Multi-page collections with a collapisible navigation menu
• URL format: hackmd.io/[@username]/[bookname]-[pagename]
• How to Create a Book

Presentations

• Make Presentation Slides with HackMD

Arweave

• How to import from/export to Arweave

Version control systems (VCS)

HackMD named versions

• See How to Save Versions
• Auto-saves every 10 minutes
• Can name auto-saved versions
• View to compare version's changes

GitHub

• See HackMD GitHub guide
• Two-way sync push and pull for all account types

GitLab

• Available with Enterprise plan: hackmd.io/pricing
• Two-way sync push and pull: Is GitLab two-way sync push and pull available? #321

Security

Data encryption and storage

• Transport Layer Security (TLS) encrypts the connection between the client and server.
• AES-256 encryption is used for data stored.
• Data is mostly stored on Amazon Web Services (AWS).
• See Is hackmd data encrypted in-transit and storage? #320

Back up notes

• Download books and projects
  • Downloading the GitHub repository of notes maintains the book/project's file's organization.
  • GitHub repository: < > Code button > Select Download ZIP
• Download all .md files: Batch Download All Your Notes 📦
• How to export to PDF

Self-hosting

Version control systems (VCS)

• Use continuous integration (CI)/continuous deployment (CD) with version control.
• See Features > version control systems (vcs)

CodiMD

• CodiMD - Realtime collaborative markdown notes on all platforms.
• CodiMD Documentation
• GitHub: github.com/hackmdio/codimd
• Questions
  • Can you migrate from HackMD to CodiMD? This would be useful for progressive decentralization.

Developer API

• HackMD API Book
• HackMD Developer Portal

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