| name | pagedrop |
| description | Create shareable HTML pages for instant mobile preview and visual collaboration. Use when building documents, visualizations, or anything that needs structure — view it in a browser from any device, then iterate with Google Docs-style annotations. |
Pagedrop
Escape the chat window. Render complex content as a shareable web page, get structured feedback via annotations.
Workflow
1. Create the HTML
Write self-contained HTML (inline CSS/JS). Save to a persistent local file using the naming convention:
/tmp/<date>-<subject>-<gist_id>.html
<date> — today's date, e.g. 2026-02-05<subject> — short slug describing the content, e.g. api-architecture, quarterly-report<gist_id> — the GitHub Gist ID (assigned after first upload). On initial creation, omit this and add it after uploading.
Why: Using the Gist ID in the filename creates a direct lookup — when annotation feedback references a gist ID, you can find the exact local file to edit. This also lets you make targeted edits instead of regenerating the entire document, which is faster and cheaper.
Default template — use Pico CSS dark theme as the base:
cat > /tmp/2026-02-05-my-preview.html << 'HTMLEOF'
<!DOCTYPE html>
<html lang="en" data-theme="dark">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>My Preview</title>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.min.css">
</head>
<body>
<main class="container">
<!-- content -->
</main>
</body>
</html>
HTMLEOF
Default share path: use /g/USER/GIST_ID. This is the normal Pagedrop route; it injects the revision and annotation UI at the edge.
Large-file fallback: if a drop is too large for /g/ injection or returns a 503, use /h/USER/GIST_ID. The /h/ route streams the raw gist HTML without edge body rewriting, so the HTML itself must include the Pagedrop bootstrap script before </body>:
<script src="https://pagedrop.ai/pagedrop.js"></script>
Because /g/ and /h/ serve the same gist, it is safe for large drops to keep this script in the HTML even when someone opens the /g/ URL. The /g/ injector avoids double-loading Pagedrop UI when the bootstrap script is already present. Do not remove it from /h/ drops unless the author explicitly wants to forego annotations, auth, sharing, and revision UI.
2. Upload and share
gh gist create /tmp/2026-02-05-my-preview.html -d "Description #pagedrop"
Always include #pagedrop in the description — this tags it as a drop so it appears in the user's profile.
After creating, capture the Gist ID from the output URL and rename the local file:
mv /tmp/2026-02-05-my-preview.html /tmp/2026-02-05-my-preview-abc123def456.html
Now the filename contains the Gist ID — a direct lookup when annotation feedback references this gist.
Note: Gists are created as secret by default (not listed on profile, not indexed). Anyone with the pagedrop.ai link can still view.
2a. Host Images/Assets (Public GitHub Repo)
If your drop needs images or other static assets, put them in a public GitHub repo (so viewers can load them). Convention:
drops/<gist_id>/... (no timestamps)
Copy/paste (example uses placeholders):
export GIST_ID="<GIST_ID>"
export USER="<USER>"
export REPO="<REPO>"
gh repo create "$USER/$REPO" --public --confirm
export ASSETS_DIR="/path/to/local/assets-repo"
git clone "git@github.com:$ORG/$REPO.git" "$ASSETS_DIR"
cd "$ASSETS_DIR"
mkdir -p "drops/$GIST_ID"
cp "/path/to/<FILE>" "drops/$GIST_ID/"
git add "drops/$GIST_ID"
git commit -m "Add assets for $GIST_ID"
git push
Raw URL pattern (replace the filename):
https://raw.githubusercontent.com/<USER>/<REPO>/<BRANCH>/drops/<GIST_ID>/<FILE>- Or: open the file on GitHub and click Raw
In your HTML:
<img src="https://raw.githubusercontent.com/<USER>/<REPO>/<BRANCH>/drops/<GIST_ID>/<FILE>" alt="Example">
In your Markdown:
Convert the gist URL to a pagedrop URL:
- Gist:
https://gist.github.com/USER/GIST_ID
- Pagedrop:
https://pagedrop.ai/g/USER/GIST_ID (default)
- Large/passthrough Pagedrop:
https://pagedrop.ai/h/USER/GIST_ID (use when /g/ is too large or returns 503; requires the bootstrap script above)
Send the pagedrop.ai URL. Works on phone, tablet, desktop.
3. Share Links
For sharing with others, use the Share button in the revision bar to generate a share link:
/s/TOKEN — share link with configurable settings
Share links let you control what viewers see:
- Show annotations — enable/disable annotation UI
- Show revisions — enable/disable revision navigation
Or create programmatically:
curl -X POST "https://pagedrop.ai/api/share" \
-H "Content-Type: application/json" \
-d '{"gist_user": "USER", "gist_id": "GIST_ID", "settings": {"annotations": true, "revisions": true}}'
4. Iterate
Edit the local file in place (use targeted edits — no need to rewrite the whole document), then push the update. The -f flag takes the gist filename (not the local path), followed by the local source file:
gh gist edit GIST_ID -f my-preview.html /tmp/2026-02-05-my-preview-GIST_ID.html
Tip: If you're unsure of the gist filename, list it first with gh gist view GIST_ID --files.
Key: Because the file persists at a known path, you can make surgical edits to specific sections rather than regenerating the full HTML each turn. This saves tokens and preserves any manual tweaks.
GitHub keeps all revisions — accessible via the revision bar or API.
Cache behavior:
/g/USER/GIST_ID — latest version (cached ~5 min)/g/USER/GIST_ID/SHA — specific revision (cached longer, immutable)/h/USER/GIST_ID — large-file passthrough route; requires the drop HTML to include https://pagedrop.ai/pagedrop.js/s/TOKEN — share link (cached ~1 min)
Recommended Libraries
Only include libraries when the content needs them. All available via CDN — no build step.
🎨 Pico CSS — Base Styling (always include)
Classless semantic CSS. Write HTML, get beautiful output. Default to dark theme.
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.min.css">
Theming:
<html data-theme="dark"> — dark theme (default for drops)<html data-theme="light"> — light theme<html data-theme="auto"> — follows OS preference
Pico handles typography, tables, forms, buttons, cards, and layout with zero classes. Just use semantic HTML (<table>, <article>, <details>, <form>, etc.).
When to use: Always. It's the base layer.
When to skip: Only if the content demands a fully custom aesthetic (dashboards, landing pages with specific brand styling).
🧜 Mermaid — Architecture & Flow Diagrams
Flowcharts, sequence diagrams, ERDs, state machines, Gantt charts, and more.
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true, theme: 'dark', securityLevel: 'loose' });
</script>
Usage in HTML:
<pre class="mermaid">
graph TD
A[User] -->|visits| B[CloudFront]
B --> C[Lambda@Edge]
C --> D[GitHub Gist]
</pre>
Theme consistency: Use theme: 'dark' with Pico dark, theme: 'default' with Pico light.
When to use: Architecture diagrams, flowcharts, sequence diagrams, ERDs, state machines, timelines.
📊 Chart.js — Charts & Plots
Simple, responsive charts with beautiful defaults.
<script src="https://cdn.jsdelivr.net/npm/chart.js@4"></script>
Usage:
<canvas id="myChart"></canvas>
<script>
new Chart(document.getElementById('myChart'), {
type: 'bar',
data: {
labels: ['Jan', 'Feb', 'Mar'],
datasets: [{
label: 'Revenue',
data: [12, 19, 3],
backgroundColor: 'rgba(88, 166, 255, 0.7)',
borderRadius: 6,
}]
},
options: {
responsive: true,
plugins: { legend: { labels: { color: '#c9d1d9' } } },
scales: {
x: { ticks: { color: '#8b949e' }, grid: { color: '#30363d' } },
y: { ticks: { color: '#8b949e' }, grid: { color: '#30363d' } }
}
}
});
</script>
Theme consistency (dark): Set color: '#c9d1d9' for labels, color: '#8b949e' for ticks, color: '#30363d' for grid lines. For light theme, omit these (Chart.js defaults are light-friendly).
When to use: Bar charts, line charts, pie/doughnut, scatter plots, radar charts. Any time there's numeric data to visualize.
💻 Prism.js — Syntax Highlighting
VS Code-quality code rendering. 300+ languages.
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css">
<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-python.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js"></script>
Usage:
<pre><code class="language-javascript">
const greeting = "Hello, world!";
console.log(greeting);
</code></pre>
Theme consistency:
- Pico dark →
prism-tomorrow.min.css (dark background, light text)
- Pico light →
prism.min.css (light background, dark text)
When to use: Any content containing code snippets. Skip if there's no code.
🧮 KaTeX — Math Rendering
Fast LaTeX math. Way faster than MathJax.
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css">
<script src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js"></script>
Usage:
<div id="equation"></div>
<script>
katex.render('E = mc^2', document.getElementById('equation'), { displayMode: true });
</script>
<script src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/auto-render.min.js"></script>
<script>renderMathInElement(document.body);</script>
With auto-render, use $$...$$ for display math and \(...\) for inline math directly in HTML text.
Theme consistency: KaTeX inherits text color from CSS — works with both Pico dark and light automatically.
When to use: Math equations, formulas, technical papers, scientific content. Skip if there's no math.
Theme Consistency Cheat Sheet
| Library | Dark mode setting | Light mode setting |
|---|
| Pico CSS | data-theme="dark" | data-theme="light" |
| Mermaid | theme: 'dark' | theme: 'default' |
| Chart.js | Custom colors (see above) | Default colors |
| Prism.js | prism-tomorrow.min.css | prism.min.css |
| KaTeX | Automatic (inherits) | Automatic (inherits) |
Rule: Pick dark or light, then match ALL libraries to that choice. Don't mix.
Library Selection Guide
Include only what the content needs:
| Content type | Libraries to include |
|---|
| Text/docs only | Pico CSS |
| Has code snippets | + Prism.js |
| Has data/metrics | + Chart.js |
| Has architecture/flows | + Mermaid |
| Has math/equations | + KaTeX |
| Dashboard with custom look | Skip Pico, use custom CSS |
Size budget (gzipped):
| Library | Size |
|---|
| Pico CSS | ~10 KB |
| Mermaid | ~300 KB |
| Chart.js | ~70 KB |
| Prism.js | ~6 KB + langs |
| KaTeX | ~90 KB |
A typical drop with all libraries loads in <500 KB. Most drops need only Pico + one other.
Annotations
The annotation UI is automatically injected on pagedrop.ai pages:
- User selects text → "Annotate" button appears
- Add comment → saved with location context
- Click "Finish" → exports structured markdown
- Paste in chat → agent addresses each point
Export Format
## Preview Feedback
**Preview:** Document Title
**Date:** 2/1/2026, 7:44:30 PM
**Annotations:** 3
---
### 1. [by @jalehman]
📍 Section: "Performance Results"
> ...reduced latency across all endpoints. Redis caching reduced validate latency by 87%, making auth nearly invisible...
This is the key win — call it out more prominently!
---
### 2. [by @collaborator]
> Sort key: UUID annotation ID
Another annotation
---
The format includes:
- Author attribution (
[by @username] or [by Anonymous])
- Location context (section heading, table position, code block)
- Selected text as blockquote
- User's comment
Notes
- Self-contained HTML — inline all CSS/JS to avoid CORS issues (CDN links are fine)
- Secret gists — not on profile or indexed, but anyone with the pagedrop.ai link can view
- Annotations — auto-injected by pagedrop.ai. Persistent for Pro users, localStorage for free
- Mobile-friendly — annotation button positioned for thumb reach
- You own your content — gists stay in your GitHub, pagedrop just proxies
- Share links — control annotations/revisions visibility for viewers
