HackMD Integration

Requirements

npm install -g @hackmd/hackmd-cli

Quick Reference

Read Notes

# List all personal notes
hackmd-cli notes

# Get note metadata (includes lastChangedAt)
hackmd-cli notes --noteId=<id> --output json

# Get note content (markdown)
hackmd-cli export --noteId=<id>

# List teams
hackmd-cli teams

# List team notes
hackmd-cli team-notes --teamPath=<path>

Write Notes

# Create note
hackmd-cli notes create --content='# Title'

# Create from file
cat file.md | hackmd-cli notes create

# Update note
hackmd-cli notes update --noteId=<id> --content='# Updated'

# Delete note
hackmd-cli notes delete --noteId=<id>

Team Notes

hackmd-cli team-notes create --teamPath=<path> --content='# Team Note'
hackmd-cli team-notes update --teamPath=<path> --noteId=<id> --content='...'
hackmd-cli team-notes delete --teamPath=<path> --noteId=<id>

Change Tracking

Use hackmd-track.js (in scripts/) to detect document changes efficiently.

Track a Note

node scripts/hackmd-track.js add <noteId>

Check for Changes

# Single note - outputs content only if changed
node scripts/hackmd-track.js changes <noteId>

# All tracked notes
node scripts/hackmd-track.js changes --all

# JSON output for parsing
node scripts/hackmd-track.js changes <noteId> --json

Manage Tracking

node scripts/hackmd-track.js list              # Show tracked notes
node scripts/hackmd-track.js remove <noteId>   # Stop tracking
node scripts/hackmd-track.js reset <noteId>    # Reset (next check shows as changed)

How It Works

hackmd-track.js add stores note's lastChangedAt timestamp
hackmd-track.js changes compares current lastChangedAt with stored value
If changed: outputs content and updates stored timestamp
If unchanged: outputs nothing (use --verbose for status)

State stored in ./.hackmd/tracked-notes.json (current working directory)

Note Metadata Fields

When using --output json, notes include:

| Field | Description | | ---------------- | ---------------------------------------- | | lastChangedAt | Unix timestamp of last modification | | lastChangeUser | {name, userPath, photo} of last editor | | titleUpdatedAt | When title changed | | tagsUpdatedAt | When tags changed |

Rate Limits

100 calls per 5 minutes
2000 calls/month (10k on Prime plan)