md-annotator 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +171 -0
  3. package/client/dist/favicon.svg +12 -0
  4. package/client/dist/index.html +2989 -0
  5. package/index.js +168 -0
  6. package/package.json +61 -0
  7. package/server/annotator.js +171 -0
  8. package/server/browser.js +20 -0
  9. package/server/config.js +36 -0
  10. package/server/feedback.js +156 -0
  11. package/server/file.js +43 -0
  12. package/server/index.js +55 -0
  13. package/server/notes.js +100 -0
  14. package/server/routes.js +151 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Konrad Michalik
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,171 @@
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="docs/images/logo-dark.png">
4
+ <source media="(prefers-color-scheme: light)" srcset="docs/images/logo-light.png">
5
+ <img alt="md-annotator" src="docs/images/logo-light.png" width="400">
6
+ </picture>
7
+ </p>
8
+
9
+ <p align="center">
10
+ An AI coding agent plugin that opens Markdown files in a local browser-based annotator.<br>
11
+ Select text to mark deletions or add comments, then let the coding agent apply your feedback.
12
+ </p>
13
+
14
+ > [!NOTE]
15
+ > 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.
16
+
17
+ ![md-annotator](docs/images/screenshot.jpg)
18
+
19
+ ## ✨ Features
20
+
21
+ - **Multi-File Support** -- Review multiple files in one session with a tabbed interface
22
+ - **Linked Navigation** -- Click relative `.md` links to open them as new tabs (wiki-style browsing)
23
+ - **Mermaid Diagrams** -- Renders `mermaid` code blocks as interactive diagrams with zoom, pan, and source toggle (adapts to light/dark theme)
24
+ - **Export & Import** -- Export annotations as Markdown or JSON; re-import JSON to continue a review later
25
+ - **Annotation Persistence** -- Annotations auto-save to the server and survive page reloads (validated by content hash)
26
+ - **Undo / Redo** -- Full undo/redo history for annotations (`Cmd+Z` / `Cmd+Shift+Z`)
27
+ - **Inline Editing** -- Click highlighted text to edit annotation type or comment in-place
28
+ - **Table of Contents** -- Collapsible sidebar with scroll tracking and per-section annotation count badges
29
+ - **Syntax Highlighting** -- Code blocks rendered with highlight.js
30
+ - **Dark Mode** -- Light, dark, and auto theme (follows system preference)
31
+ - **Auto-Close Tab** -- Opt-in countdown that closes the browser tab after submitting feedback
32
+ - **Update Notifications** -- Banner when a new GitHub release is available
33
+ - **Heartbeat Detection** -- Graceful shutdown when the browser tab is closed
34
+ - **IDE Integration** -- Annotate the currently open file in VSCode, Cursor, or JetBrains without arguments
35
+
36
+ ## Prerequisites
37
+
38
+ - **Node.js** 22+ and **npm**
39
+ - A modern **browser** (opens automatically)
40
+
41
+ ## 🔌 Claude Code Plugin
42
+
43
+ *md-annotator* is a Claude Code plugin. After installation the slash command `/annotate:md` is available in any Claude Code session.
44
+
45
+ ### 📦 Installation
46
+
47
+ ```bash
48
+ # Install the CLI
49
+ npm install -g md-annotator
50
+
51
+ # Add the marketplace
52
+ claude plugin marketplace add konradmichalik/md-annotator
53
+
54
+ # Install the plugin
55
+ claude plugin install annotate@md-annotator --scope user
56
+ ```
57
+
58
+ For local development, see the [Development](#development) section.
59
+
60
+ ### 🔄 Update
61
+
62
+ ```bash
63
+ # Update the marketplace cache first
64
+ claude plugin marketplace update md-annotator
65
+
66
+ # Then update the plugin
67
+ claude plugin update annotate@md-annotator
68
+ ```
69
+
70
+ ### 🚀 Usage
71
+
72
+ Inside a Claude Code session:
73
+
74
+ ```
75
+ /annotate:md README.md
76
+ /annotate:md docs/api.md docs/guide.md
77
+ ```
78
+
79
+ Or, with IDE integration (VSCode/Cursor/JetBrains), just run without arguments to annotate the currently open file:
80
+
81
+ ```
82
+ /annotate:md
83
+ ```
84
+
85
+ This opens the file in your browser. You can then:
86
+
87
+ - **Select text** to see the annotation toolbar
88
+ - **Delete** -- marks text as struck-through (red)
89
+ - **Comment** -- highlights text (yellow) and adds a comment
90
+ - **Insert** -- place the cursor to add new text at that position
91
+ - **Global Comment** -- add general feedback via the "+" button in the annotation panel
92
+ - **Annotate images & diagrams** -- click on images or Mermaid diagrams to comment or delete them
93
+ - **View annotations** in the sidebar panel on the right
94
+ - **Export** annotations as Markdown or JSON
95
+ - **Approve** or **Submit Feedback** when done
96
+
97
+ ## 🔷 OpenCode Plugin
98
+
99
+ *md-annotator* is also available as an OpenCode plugin.
100
+
101
+ ### 📦 Installation
102
+
103
+ Add to your `opencode.json`:
104
+
105
+ ```json
106
+ {
107
+ "plugins": ["@md-annotator/opencode"]
108
+ }
109
+ ```
110
+
111
+ ### 🚀 Usage
112
+
113
+ The agent can use the `annotate_markdown` tool:
114
+
115
+ ```
116
+ annotate_markdown({ filePath: "/path/to/file.md" })
117
+ annotate_markdown({ filePaths: ["/path/to/a.md", "/path/to/b.md"] })
118
+ ```
119
+
120
+ Or use the `/annotate:md` command in the chat.
121
+
122
+ ## 💻 Standalone CLI
123
+
124
+ *md-annotator* also works as a standalone CLI tool without an AI coding agent:
125
+
126
+ ```bash
127
+ # Single file
128
+ md-annotator README.md
129
+
130
+ # Multiple files (opens with tab bar)
131
+ md-annotator docs/api.md docs/guide.md
132
+
133
+ # Or link globally first
134
+ npm link
135
+
136
+ # Show help
137
+ md-annotator --help
138
+ ```
139
+
140
+ The 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.
141
+
142
+ ### Environment Variables
143
+
144
+ | Variable | Description |
145
+ |----------|-------------|
146
+ | `MD_ANNOTATOR_PORT` | Override the server port (default: 3000) |
147
+ | `MD_ANNOTATOR_BROWSER` | Custom browser application |
148
+
149
+ ## 🛠️ Development
150
+
151
+ ```bash
152
+ # Clone and build
153
+ git clone https://github.com/konradmichalik/md-annotator.git
154
+ cd md-annotator
155
+ npm install && npm run build
156
+
157
+ # Install local plugin for testing
158
+ claude plugin install ./apps/claude-code --scope user
159
+
160
+ # Development commands
161
+ npm run dev:client # Vite dev server with HMR (client only)
162
+ npm run build # Production build (single-file HTML)
163
+ npm run dev # CLI with --watch
164
+
165
+ # Test plugin without permanent installation
166
+ claude --plugin-dir ./apps/claude-code
167
+ ```
168
+
169
+ ## 📄 License
170
+
171
+ MIT
package/client/dist/favicon.svg ADDED
@@ -0,0 +1,12 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="12 -18 232 232">
2
+ <style>
3
+ .md { fill: #1a1a1a; }
4
+ @media (prefers-color-scheme: dark) {
5
+ .md { fill: #e5e5e5; }
6
+ }
7
+ </style>
8
+ <g class="md" fill-rule="nonzero" transform="translate(-51.9375,-433.25)">
9
+ <path d="M168.625,539.5C169.042,537.583 169.5,535.521 170,533.313C170.5,531.104 170.75,529.375 170.75,528.125C170.75,526.542 170.479,525.292 169.938,524.375C169.396,523.458 168.417,523 167,523C165.583,523 164.125,523.521 162.625,524.563C161.125,525.604 159.667,526.979 158.25,528.688C156.833,530.396 155.479,532.333 154.188,534.5C152.896,536.667 151.75,538.875 150.75,541.125L142.625,577L125.875,577L133.5,541.875C134.083,539.292 134.583,536.792 135,534.375C135.417,531.958 135.625,529.708 135.625,527.625C135.625,524.542 134.458,523 132.125,523C130.958,523 129.625,523.542 128.125,524.625C126.625,525.708 125.125,527.104 123.625,528.813C122.125,530.521 120.708,532.458 119.375,534.625C118.042,536.792 117,539 116.25,541.25L109,577L91.5,577L102.625,523.375L95.5,521.75L95.5,517.5C96.833,516.833 98.479,516.208 100.438,515.625C102.396,515.042 104.458,514.563 106.625,514.188C108.792,513.813 111,513.521 113.25,513.313C115.5,513.104 117.583,513 119.5,513L122.125,514.5L117.25,532.75L117.75,532.75C119,530.5 120.521,528.188 122.312,525.813C124.104,523.438 126.125,521.313 128.375,519.438C130.625,517.563 133.042,516.021 135.625,514.813C138.208,513.604 140.833,513 143.5,513C144.5,513 145.542,513.167 146.625,513.5C147.708,513.833 148.729,514.438 149.688,515.313C150.646,516.188 151.417,517.375 152,518.875C152.583,520.375 152.875,522.292 152.875,524.625C152.875,525.792 152.771,527.125 152.562,528.625C152.354,530.125 152.083,531.5 151.75,532.75C153.167,530.167 154.833,527.667 156.75,525.25C158.667,522.833 160.729,520.729 162.938,518.938C165.146,517.146 167.479,515.708 169.938,514.625C172.396,513.542 174.958,513 177.625,513C180.792,513 183.375,514 185.375,516C187.375,518 188.375,520.75 188.375,524.25C188.375,526.917 188.125,529.458 187.625,531.875C187.125,534.292 186.583,536.833 186,539.5L178.875,568.375L187.625,568.375L187.625,572.625C186.792,573.292 185.646,573.958 184.188,574.625C182.729,575.292 181.167,575.875 179.5,576.375C177.833,576.875 176.125,577.292 174.375,577.625C172.625,577.958 171,578.125 169.5,578.125C166.5,578.125 164.417,577.521 163.25,576.313C162.083,575.104 161.5,573.75 161.5,572.25C161.5,569.833 162.083,566.5 163.25,562.25L168.625,539.5Z"/>
10
+ <path d="M221,568.5C222.75,568.5 224.479,567.771 226.188,566.313C227.896,564.854 229.521,563.042 231.062,560.875C232.604,558.708 234.021,556.375 235.312,553.875C236.604,551.375 237.708,549.083 238.625,547L243.125,522.375C242.042,521.708 241.021,521.229 240.062,520.938C239.104,520.646 237.958,520.5 236.625,520.5C233.458,520.5 230.562,521.563 227.938,523.688C225.312,525.813 223.083,528.604 221.25,532.063C219.417,535.521 218,539.479 217,543.938C216,548.396 215.5,552.958 215.5,557.625C215.5,564.875 217.333,568.5 221,568.5ZM236.625,557.125C235.375,560.042 233.896,562.792 232.188,565.375C230.479,567.958 228.604,570.208 226.562,572.125C224.521,574.042 222.292,575.583 219.875,576.75C217.458,577.917 214.917,578.5 212.25,578.5C208,578.5 204.521,576.875 201.812,573.625C199.104,570.375 197.75,565.458 197.75,558.875C197.75,552.958 198.562,547.271 200.188,541.813C201.812,536.354 204.188,531.521 207.312,527.313C210.438,523.104 214.271,519.729 218.812,517.188C223.354,514.646 228.542,513.375 234.375,513.375C237.125,513.375 239.146,513.542 240.438,513.875C241.729,514.208 243.083,514.708 244.5,515.375L248.75,493.375L240.125,491.75L240.125,487.5C241.375,487 243.083,486.5 245.25,486C247.417,485.5 249.729,485.042 252.188,484.625C254.646,484.208 257.062,483.854 259.438,483.563C261.812,483.271 263.75,483.083 265.25,483L267.75,484.375L251.625,568.375L260.625,568.375L260.625,572.625C259.792,573.292 258.688,573.958 257.312,574.625C255.938,575.292 254.438,575.875 252.812,576.375C251.188,576.875 249.5,577.292 247.75,577.625C246,577.958 244.375,578.125 242.875,578.125C239.958,578.125 237.875,577.458 236.625,576.125C235.375,574.792 234.75,573.417 234.75,572C234.75,570.583 234.958,568.542 235.375,565.875C235.792,563.208 236.375,560.292 237.125,557.125L236.625,557.125Z"/>
11
+ </g>
12
+ </svg>