hackmdio / hackmdio/hackmd-io-issues
API and export support for comments and reactions
- Dominant language
- No language data
- Stars
- 40
- Forks
- 9
- PR merge metrics
- No merged PRs in 30d
Description
## Problem
Comments and reactions are first-class collaboration features in HackMD — the [new commenting system](https://hackmd.io/@hackmd-blog/a-new-era-of-commenting) 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:**
```json
[
{
"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
```bash
hackmd-cli export --noteId= --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`](https://developers.notion.com/reference/retrieve-comment) 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
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.