API and export support for comments and reactions

[ealt]

Problem

Comments and reactions are first-class collaboration features in HackMD — the new commenting system introduced in 2024 added emoji reactions, a dedicated side panel, and expanded character limits. However, none of this data is accessible through the API, CLI, GitHub sync, or any export format.

Teams that use HackMD as part of a GitHub-centered documentation workflow lose all review context (feedback, questions, decisions captured in comment threads) when syncing notes to their repository. The comments are effectively trapped on the HackMD platform with no way to extract them.

Use Case

Our team recently migrated from Google Docs to a stack of HackMD + GitHub + Obsidian for collaborative documentation. HackMD replaced Google Docs as the real-time collaboration layer, with GitHub as the source of truth.

On Google Docs, comments traveled with the document — they could be exported, and the full discussion history was preserved. On HackMD, comments and reactions are silently dropped the moment a note is synced to GitHub. This is the single biggest gap in our workflow, and the main reason we can't fully move off Google Docs.

Current State

• API v1: No endpoints for retrieving comment or reaction data. The only comment-related field is commentPermission (who can comment), but actual comment content is inaccessible.
• CLI (hackmd-cli export): Outputs note.content only — raw markdown, no comments.
• GitHub sync: Pushes markdown content as commits. Comments and reactions are not included.
• All export formats (PDF, Dropbox, Google Drive, Arweave): Omit comments entirely.

Proposed Solution

Tier 1: API endpoints (highest priority)

New REST endpoints to retrieve comment and reaction data:

GET /v1/notes/:noteId/comments
GET /v1/notes/:noteId/reactions

Suggested comment response schema:

[
  {
    "id": "comment-id",
    "author": {
      "id": "user-id",
      "name": "Display Name"
    },
    "body": "Comment text content",
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T10:30:00Z",
    "resolved": false,
    "range": {
      "startLine": 42,
      "endLine": 44
    },
    "replies": [
      {
        "id": "reply-id",
        "author": { "id": "user-id", "name": "Display Name" },
        "body": "Reply text",
        "createdAt": "2025-01-15T11:00:00Z"
      }
    ],
    "reactions": [
      {
        "emoji": "👍",
        "users": ["user-id-1", "user-id-2"]
      }
    ]
  }
]

Tier 2: CLI export flag

hackmd-cli export --noteId=<id> --include-comments

This would output a sidecar .comments.json file alongside the markdown content, enabling scripted workflows and backups.

Tier 3: GitHub sync enrichment

Option to sync comments alongside note content, either as:

• A sidecar .comments.json committed to the repo, or
• Mapped to GitHub PR review comments (for notes synced via PR workflow)

Prior Art

• Google Docs: Export includes comments; Google Docs API provides full comment/reply access
• Notion API: GET /v1/comments endpoint exposes all comments on a page
• GitHub: Issues and PR APIs expose all comments and reactions

Impact

This is a blocker for teams that want to use HackMD's collaboration features while maintaining durable records of discussion. Without it, the collaboration context that makes HackMD valuable over a plain text editor is ephemeral and lost.

Related: #207