{"id":47948350,"url":"https://github.com/konradmichalik/md-annotator","last_synced_at":"2026-04-04T08:53:24.952Z","repository":{"id":340138952,"uuid":"1144164151","full_name":"konradmichalik/md-annotator","owner":"konradmichalik","description":"📄 AI coding agent plugin that opens Markdown files in a local browser-based annotator.","archived":false,"fork":false,"pushed_at":"2026-04-02T12:43:39.000Z","size":1104,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T08:53:21.115Z","etag":null,"topics":["claude-code","claude-code-plugins","opencode","opencode-plugin"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/konradmichalik.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-28T11:18:02.000Z","updated_at":"2026-04-02T12:43:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/konradmichalik/md-annotator","commit_stats":null,"previous_names":["konradmichalik/md-annotator"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/konradmichalik/md-annotator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konradmichalik%2Fmd-annotator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konradmichalik%2Fmd-annotator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konradmichalik%2Fmd-annotator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konradmichalik%2Fmd-annotator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/konradmichalik","download_url":"https://codeload.github.com/konradmichalik/md-annotator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konradmichalik%2Fmd-annotator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31393781,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T04:26:24.776Z","status":"ssl_error","status_checked_at":"2026-04-04T04:23:34.147Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","claude-code-plugins","opencode","opencode-plugin"],"created_at":"2026-04-04T08:53:24.277Z","updated_at":"2026-04-04T08:53:24.937Z","avatar_url":"https://github.com/konradmichalik.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/images/logo-dark.png\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"docs/images/logo-light.png\"\u003e\n    \u003cimg alt=\"md-annotator\" src=\"docs/images/logo-light.png\" width=\"400\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  An AI coding agent plugin that opens Markdown files in a local browser-based annotator.\u003cbr\u003e\n  Select text to mark deletions or add comments, then let the coding agent apply your feedback.\n\u003c/p\u003e\n\n\u003e [!NOTE]\n\u003e This plugin is heavily inspired by the excellent [plannotator](https://plannotator.ai/) plugin and uses a similar general approach for Markdown files. Useful for reviewing documentation in software projects.\n\n![md-annotator](docs/images/screenshot.jpg)\n\n## ✨ Features\n\n- **Multi-File Support** -- Review multiple files in one session with a tabbed interface\n- **Linked Navigation** -- Click relative `.md` links to open them as new tabs (wiki-style browsing)\n- **Mermaid Diagrams** -- Renders `mermaid` code blocks as interactive diagrams with zoom, pan, and source toggle (adapts to light/dark theme)\n- **PlantUML Diagrams** -- Renders `plantuml` code blocks as SVG via a configurable PlantUML server with zoom, pan, and source toggle\n- **Kroki Diagrams** -- Renders 27+ diagram formats (`graphviz`, `d2`, `ditaa`, `erd`, `nomnoml`, `excalidraw`, and more) via a configurable [Kroki](https://kroki.io) server\n- **File References** -- Type `@` in comments to autocomplete and reference other project files\n- **Export \u0026 Import** -- Export annotations as Markdown or JSON; re-import JSON to continue a review later\n- **Annotation Persistence** -- Annotations auto-save to the server and survive page reloads (validated by content hash)\n- **Undo / Redo** -- Full undo/redo history for annotations (`Cmd+Z` / `Cmd+Shift+Z`)\n- **Quick Labels** -- Categorize annotations instantly with 10 predefined labels (`Alt+1`--`0`) shown as colored pills with SVG icons\n- **Inline Editing** -- Click highlighted text to edit annotation type or comment in-place\n- **Table of Contents** -- Collapsible sidebar with scroll tracking and per-section annotation count badges\n- **Syntax Highlighting** -- Code blocks rendered with highlight.js\n- **Dark Mode** -- Light, dark, and auto theme (follows system preference)\n- **Auto-Close Tab** -- Opt-in countdown that closes the browser tab after submitting feedback\n- **Update Notifications** -- Banner when a new GitHub release is available\n- **Heartbeat Detection** -- Graceful shutdown when the browser tab is closed\n- **IDE Integration** -- Annotate the currently open file in VSCode, Cursor, or JetBrains without arguments\n- **Iterative Review** -- AI agent applies your feedback and re-opens the annotator for another review round until you approve\n\n## 📋 Prerequisites\n\n- **Node.js** 22+ and **npm**\n- A modern **browser** (opens automatically)\n\n## 🔗 Integrations\n\n*md-annotator* supports the following integrations:\n\n- [**Claude Code**](#-claude-code-plugin) -- Plugin with `/annotate:md` slash command\n- [**OpenCode**](#-opencode-plugin) -- Plugin with `annotate_markdown` tool and `/annotate:md` command\n- [**Standalone CLI**](#-standalone-cli) -- Use directly from the terminal without an AI agent\n\n## 🔌 Claude Code Plugin\n\n*md-annotator* is a Claude Code plugin. After installation the slash command `/annotate:md` is available in any Claude Code session.\n\n### 📦 Installation \u0026 Update\n\n```bash\ncurl -fsSL https://konradmichalik.github.io/md-annotator/install.sh | bash\n```\n\n### 🚀 Usage\n\nInside a Claude Code session:\n\n```\n/annotate:md README.md\n/annotate:md docs/api.md docs/guide.md\n```\n\nOr, with IDE integration (VSCode/Cursor/JetBrains), just run without arguments to annotate the currently open file:\n\n```\n/annotate:md\n```\n\n## 🔷 OpenCode Plugin\n\n*md-annotator* is also available as an OpenCode plugin.\n\n### 📦 Installation \u0026 Update\n\n```bash\ncurl -fsSL https://konradmichalik.github.io/md-annotator/install.sh | bash\n```\n\nThen add to your `opencode.json`:\n\n```json\n{\n  \"plugin\": [\"md-annotator-opencode@latest\"]\n}\n```\n\n\u003e [!NOTE]\n\u003e See [OpenCode documentation](https://opencode.ai/docs/plugins) for more details.\n\n### 🚀 Usage\n\nUse the `/annotate:md` command in the chat:\n\n```\n/annotate:md README.md\n/annotate:md docs/api.md docs/guide.md\n```\n\nThe agent can also use the `annotate_markdown` tool directly:\n\n```\nannotate_markdown({ filePath: \"/path/to/file.md\" })\nannotate_markdown({ filePaths: [\"/path/to/a.md\", \"/path/to/b.md\"] })\n```\n\n## 💻 Standalone CLI\n\n*md-annotator* also works as a standalone CLI tool without an AI coding agent:\n\n```bash\n# Single file\nmd-annotator README.md\n\n# Multiple files (opens with tab bar)\nmd-annotator docs/api.md docs/guide.md\n\n# Show help\nmd-annotator --help\n```\n\nThe server starts on an available port (default 3000) and opens your browser automatically. When reviewing multiple files, a tab bar appears for switching between them. Clicking relative `.md` links inside a document opens the linked file as a new tab.\n\n### Environment Variables\n\n| Variable               | Description                                                  |\n|------------------------|--------------------------------------------------------------|\n| `MD_ANNOTATOR_PORT`    | Override the server port (default: 3000)                     |\n| `MD_ANNOTATOR_BROWSER` | Custom browser application                                   |\n| `PLANTUML_SERVER_URL`  | PlantUML render server (default: `https://www.plantuml.com/plantuml`) |\n| `KROKI_SERVER_URL`     | Kroki render server (default: `https://kroki.io`)                    |\n\n\u003e [!NOTE]\n\u003e **Privacy**: When rendering PlantUML or Kroki diagrams, the diagram source is encoded and sent to the configured server. The defaults are the public servers at `plantuml.com` and `kroki.io`. If your documents contain sensitive diagrams, self-host a [PlantUML server](https://hub.docker.com/r/plantuml/plantuml-server) or [Kroki server](https://docs.kroki.io/kroki/setup/install/) and set `PLANTUML_SERVER_URL` / `KROKI_SERVER_URL` accordingly.\n\n## 📝 How It Works\n\nOnce a file is opened in the browser, you can:\n\n- **Select text** to see the annotation toolbar\n- **Delete** -- marks text as struck-through (red)\n- **Comment** -- highlights text (yellow) and adds a comment\n- **Quick Label** -- click the tag icon or press `Alt+1`--`0` to instantly categorize a selection (Unclear, Rephrase, Factual Error, etc.)\n- **Insert** -- place the cursor to add new text at that position\n- **Global Comment** -- add general feedback via the \"+\" button in the annotation panel\n- **Annotate images \u0026 diagrams** -- click on images, Mermaid, PlantUML, or Kroki diagrams to comment or delete them\n- **View annotations** in the sidebar panel on the right\n- **Export** annotations as Markdown or JSON\n- **Approve** or **Submit Feedback** when done\n\nWhen used with an AI agent (Claude Code or OpenCode), submitting feedback triggers the agent to apply your changes to the file. The agent then re-opens the annotator for another review round, so you can verify the edits and provide further feedback if needed. This review loop continues until you approve the result.\n\n## 🛠️ Development\n\nSee [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for setup, build commands, and local plugin testing.\n\n## 📄 License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkonradmichalik%2Fmd-annotator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkonradmichalik%2Fmd-annotator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkonradmichalik%2Fmd-annotator/lists"}