hackmdio / hackmdio/hackmd-io-issues

API and export support for comments and reactions

Open
#428 0 comments 3 reactions 0 assignees View on GitHub
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.