Skip to content

Commit e410ac2

Browse files
backnotpropbacknotprop
authored
docs(annotate): add URL/HTML docs, blog post, and env var references (#553)
- Rewrote the annotate command docs page to cover all four input types (URLs, HTML files, folders, markdown) with Jina Reader pipeline details, --no-jina flag, JINA_API_KEY, and source badge - Added PLANNOTATOR_JINA and JINA_API_KEY to the environment variables reference page - New blog post: "Annotate Any Web Page or HTML File" with embedded video For provenance purposes, this commit was AI assisted.
1 parent 81ae7f6 commit e410ac2

3 files changed

Lines changed: 143 additions & 25 deletions

File tree

‎apps/marketing/src/content/blog/annotate-any-web-page-or-html-file.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
title: "Annotate Any Web Page or HTML File"
3+
description: "Plannotator's /plannotator-annotate command now accepts URLs and HTML files, not just markdown. Fetch any web page, convert it to markdown, and annotate it with structured feedback for your coding agent."
4+
date: 2026-04-12
5+
author: "backnotprop"
6+
tags: ["annotate", "url", "html", "jina-reader"]
7+
---
8+
9+
**Plannotator is an open-source review UI for AI coding agents.** The `/plannotator-annotate` command now accepts URLs and HTML files alongside markdown, so you can pull in any external documentation, convert it on the fly, and send structured annotations back to your agent session.
10+
11+
<video width="100%" style="aspect-ratio: 16/9; border-radius: 8px; margin-bottom: 1.5rem;" autoplay loop muted playsinline controls><source src="https://d17ygohy796f9l.cloudfront.net/videos/annotate-url.mp4" type="video/mp4" /></video>
12+
13+
## The problem
14+
15+
You're working with an agent that needs to implement against an external API or follow a specific guide. You could copy-paste the documentation into chat, but you lose structure. You could describe what you need freeform, but that's imprecise. What you actually want is to open the page, highlight the relevant sections, and send that annotated content directly to the agent.
16+
17+
This was a [community-requested feature](https://github.com/backnotprop/plannotator/issues) that ships in [PR #545](https://github.com/backnotprop/plannotator/pull/545).
18+
19+
## What you can do now
20+
21+
```bash
22+
plannotator annotate https://docs.stripe.com/api # remote URL
23+
plannotator annotate docs/guide.html # local HTML file
24+
plannotator annotate ./docs/ # folder (now includes .html files)
25+
plannotator annotate https://... --no-jina # direct fetch, no Jina
26+
```
27+
28+
All inputs are converted to markdown before reaching the annotation editor. You annotate, highlight, comment, and when you click Send Annotations, structured feedback goes back to the agent session.
29+
30+
Local HTML files are read from disk and converted via Turndown. Folders now show `.html` and `.htm` files alongside markdown in the file browser, with conversion happening on demand. A source attribution badge appears under the document title so you know what you're looking at.
31+
32+
## How URL fetching works
33+
34+
By default, URLs are fetched through [Jina Reader](https://jina.ai/reader/) (`r.jina.ai`). Jina handles JavaScript-rendered pages, strips navigation and boilerplate, and returns clean markdown. Most documentation sites work well with it.
35+
36+
If the URL ends in `.md` or `.mdx`, Plannotator fetches it raw and skips conversion entirely.
37+
38+
For cases where you want to skip Jina, use `--no-jina`. Plannotator will fetch the page directly and run Turndown locally.
39+
40+
## Configuration
41+
42+
Three ways to configure Jina behavior:
43+
44+
- **CLI flag**: `plannotator annotate https://... --no-jina`
45+
- **Environment variable**: `PLANNOTATOR_JINA=0`
46+
- **Config file**: `~/.plannotator/config.json` with `{ "jina": false }`
47+
48+
For higher rate limits (500 RPM instead of 20 RPM), set a `JINA_API_KEY`. Free keys are available from Jina and include 10M tokens.
49+
50+
## Try it
51+
52+
Install or update Plannotator:
53+
54+
```bash
55+
curl -fsSL https://plannotator.ai/install.sh | bash
56+
```
57+
58+
Then run the annotate command with any URL or HTML file. Annotate the relevant sections and send the feedback to your agent. Full docs at [plannotator.ai/docs](/docs/getting-started/installation/).

‎apps/marketing/src/content/docs/commands/annotate.md‎

Lines changed: 78 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,94 @@
11
---
22
title: "Annotate"
3-
description: "The /plannotator-annotate slash command for annotating any markdown file."
3+
description: "The /plannotator-annotate slash command for annotating markdown files, HTML files, URLs, and folders."
44
sidebar:
55
order: 12
66
section: "Commands"
77
---
88

9-
The `/plannotator-annotate` command opens any markdown file in the Plannotator annotation UI.
9+
The `/plannotator-annotate` command opens files, URLs, or folders in the Plannotator annotation UI.
1010

11-
## Usage
11+
## What you can annotate
12+
13+
| Input | Command | What happens |
14+
|-------|---------|--------------|
15+
| Markdown file | `plannotator annotate README.md` | Opens the file directly |
16+
| HTML file | `plannotator annotate docs/guide.html` | Converts to markdown via Turndown, then opens |
17+
| URL | `plannotator annotate https://docs.stripe.com/api` | Fetches the page, converts to markdown, then opens |
18+
| Folder | `plannotator annotate ./docs/` | Opens a file browser showing all `.md`, `.mdx`, `.html`, and `.htm` files |
1219

1320
### Slash command (inside an agent session)
1421

1522
```
1623
/plannotator-annotate path/to/file.md
24+
/plannotator-annotate https://docs.stripe.com/api
25+
/plannotator-annotate ./specs/
1726
```
1827

19-
The agent runs `plannotator annotate <file>` under the hood. The annotation UI opens in the browser. When you submit, feedback is returned to the agent as structured output.
28+
The agent runs `plannotator annotate <arg>` under the hood. The annotation UI opens in the browser. When you submit, feedback is returned to the agent as structured output.
2029

2130
### Standalone CLI (outside an agent session)
2231

2332
```bash
2433
plannotator annotate path/to/file.md
34+
plannotator annotate index.html
35+
plannotator annotate https://example.com/docs
36+
plannotator annotate ./docs/
2537
```
2638

27-
This starts a local server, opens the browser, and blocks until you submit. The formatted feedback is printed to stdout.
39+
Starts a local server, opens the browser, and blocks until you submit. Formatted feedback is printed to stdout.
2840

29-
## How it works
41+
## Folders
3042

43+
When you pass a folder, Plannotator opens a file browser showing all markdown and HTML files in the directory tree. Click any file to open it in the annotation UI. This is useful for annotating a set of specs, documentation, or your Obsidian vault.
44+
45+
Build output directories like `_site/`, `public/`, `.docusaurus/`, and `node_modules/` are automatically excluded from the file browser.
46+
47+
## URLs
48+
49+
Fetching a URL converts the page to markdown before opening it in the annotation editor.
50+
51+
### Jina Reader (default)
52+
53+
By default, URLs are fetched through [Jina Reader](https://jina.ai/reader/) (`r.jina.ai`). Jina handles JavaScript-rendered pages and returns clean, reader-mode markdown. This works well for documentation sites, blog posts, and API references.
54+
55+
Set `JINA_API_KEY` in your environment for higher rate limits (500 req/min vs 20 req/min unauthenticated). Free API keys are available from Jina.
56+
57+
### Direct fetch (`--no-jina`)
58+
59+
If you don't want to use Jina, pass `--no-jina`. Plannotator will fetch the HTML directly and convert it with Turndown. This is useful for pages behind authentication, internal docs, or when you just prefer not to route through a third-party service.
60+
61+
```bash
62+
plannotator annotate https://internal.company.com/docs --no-jina
3163
```
32-
User runs /plannotator-annotate README.md
33-
↓
34-
CLI reads README.md from disk
35-
↓
36-
Annotate server starts (random port)
37-
↓
38-
Browser opens, loads annotation UI
39-
↓
40-
/api/plan returns { plan: markdown, mode: "annotate" }
41-
↓
42-
User annotates → Send Annotations
43-
↓
44-
POST /api/feedback with exported feedback
45-
↓
46-
Server prints feedback to stdout, exits
47-
```
64+
65+
### .md and .mdx URLs
66+
67+
URLs ending in `.md` or `.mdx` are fetched as raw text with no conversion. If the server returns HTML instead (like GitHub's rendered markdown viewer), Plannotator falls through to Jina or Turndown automatically.
68+
69+
### Local and private URLs
70+
71+
URLs pointing to `localhost`, `127.x.x.x`, `10.x.x.x`, `192.168.x.x`, and other private or link-local addresses always use direct fetch. Jina is skipped automatically since it can't reach private networks.
72+
73+
### Configuring Jina
74+
75+
Three ways to disable Jina Reader, in priority order:
76+
77+
1. **CLI flag:** `--no-jina`
78+
2. **Environment variable:** `PLANNOTATOR_JINA=0` or `PLANNOTATOR_JINA=false`
79+
3. **Config file:** `~/.plannotator/config.json` with `{ "jina": false }`
80+
81+
If none of these are set, Jina is enabled by default.
82+
83+
## HTML files
84+
85+
Local `.html` and `.htm` files are read from disk and converted to markdown using [Turndown](https://github.com/mixmark-io/turndown) with GFM table support. `<script>`, `<style>`, and `<noscript>` tags are stripped before conversion.
86+
87+
HTML files must be within your current working directory. Files outside the project root return a 403 error.
88+
89+
## Source badge
90+
91+
When annotating an HTML file or URL (not plain markdown), a small badge appears under the document title showing where the content came from. For URLs it shows the hostname (e.g. "stripe.com"). For HTML files it shows the filename (e.g. "guide.html").
4892

4993
## Annotate mode differences
5094

@@ -55,7 +99,7 @@ The annotation UI in annotate mode works the same as plan review, with a few cha
5599
- `Cmd/Ctrl+Enter` sends annotations instead of approving
56100
- The completion screen says "Annotations Sent" instead of "Plan Approved"
57101

58-
All annotation types work identically — deletions, replacements, comments, insertions, global comments, and image attachments.
102+
All annotation types work identically: deletions, replacements, comments, insertions, global comments, and image attachments.
59103

60104
## Feedback format
61105

@@ -84,11 +128,20 @@ The agent receives this and can act on each annotation.
84128

85129
| Endpoint | Method | Purpose |
86130
|----------|--------|---------|
87-
| `/api/plan` | GET | Returns `{ plan, mode: "annotate", filePath }` |
131+
| `/api/plan` | GET | Returns `{ plan, mode: "annotate", filePath, sourceInfo }` |
88132
| `/api/feedback` | POST | Submit annotations |
133+
| `/api/exit` | POST | Close session without feedback |
89134
| `/api/image` | GET | Serve image by path |
90135
| `/api/upload` | POST | Upload image attachment |
136+
| `/api/draft` | GET/POST/DELETE | Auto-save annotation drafts |
91137

92138
## Environment variables
93139

94-
The annotate server respects the same environment variables as plan review. See the [environment variables reference](/docs/reference/environment-variables/).
140+
The annotate server respects the same environment variables as plan review, plus two specific to URL annotation:
141+
142+
| Variable | Default | Description |
143+
|----------|---------|-------------|
144+
| `PLANNOTATOR_JINA` | enabled | Set to `0` or `false` to disable Jina Reader for URL annotation. |
145+
| `JINA_API_KEY` | (none) | Optional Jina Reader API key for higher rate limits (500 RPM vs 20 RPM). |
146+
147+
See the [environment variables reference](/docs/reference/environment-variables/) for all options.

‎apps/marketing/src/content/docs/reference/environment-variables.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,13 @@ All Plannotator environment variables and their defaults.
2020
| `PLANNOTATOR_SHARE_URL` | `https://share.plannotator.ai` | Base URL for share links. Set this when self-hosting the share portal. |
2121
| `PLANNOTATOR_PLAN_TIMEOUT_SECONDS` | `345600` | OpenCode only. `submit_plan` wait timeout in seconds. Set `0` to disable timeout. |
2222

23+
## Annotation variables
24+
25+
| Variable | Default | Description |
26+
|----------|---------|-------------|
27+
| `PLANNOTATOR_JINA` | enabled | Set to `0` or `false` to disable Jina Reader for URL annotation. Set to `1` or `true` to enable (this is the default). Can also be set via `~/.plannotator/config.json` (`{ "jina": false }`) or per-invocation via `--no-jina`. |
28+
| `JINA_API_KEY` | (none) | Optional Jina Reader API key for higher rate limits. Without it: 20 req/min. With it: 500 req/min. Free keys available from [Jina](https://jina.ai/reader/) and include 10M tokens. |
29+
2330
## Paste service variables
2431

2532
| Variable | Default | Description |

0 commit comments

Comments
 (0)