Add .agents/SKILL.md — authoring guide for HTML docs

Author: smcllns

.agents/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: obsidian-html-docs
+description: Author HTML files for the Obsidian HTML Docs plugin (smcllns/obsidian-plugin-html-docs). Use when creating .html docs intended to render inline in Obsidian — covers the context the plugin provides, sandbox constraints, asset rules, and the things that silently don't work.
+---
+
+# Obsidian HTML Docs — authoring guide
+
+The plugin enables the user to view html files inside Obsidian, similar to md files. The plugin renders `.html` in a sandboxed iframe via Blob URL. The iframe is sealed (`sandbox="allow-scripts allow-popups allow-forms"`, no `allow-same-origin`) so it can't reach into Obsidian or the vault. Everything below works within that envelope.
+
+## Default to Obsidian's context — unless asked otherwise
+
+Before sealing the iframe, the plugin can prepend a `<style>` block to your HTML containing a snapshot of the user's current Obsidian design tokens. The iframe doesn't reach out for these values — they're written as static CSS into your document at load time, then the sandbox is applied. **Security boundary unchanged** (no `allow-same-origin`, no reads from the iframe back into Obsidian); the iframe just has a few extra CSS variables declared in its own document.
+
+If the user just wants a styled doc that "fits" their vault, use these as your defaults. If they're asking for a specific aesthetic (brutalist poster, retro terminal, Linear-style, an exact brand palette), design freely — Obsidian context is a *hint*, not a constraint.
+
+**Injected as static CSS** (proposed plugin enhancement; today only `color-scheme: light dark` via OS preference works):
+
+- A `color-scheme: light | dark` declaration matching the user's current Obsidian theme
+- A small set of `--obsidian-*` CSS variables holding snapshot values from the user's active Obsidian theme: `--obsidian-bg`, `--obsidian-bg-2`, `--obsidian-text`, `--obsidian-text-muted`, `--obsidian-accent`, `--obsidian-border`, `--obsidian-font`, `--obsidian-font-mono`
+
+**Graceful pattern** — use Obsidian tokens if present, fall back if not:
+
+```css
+:root {
+  color-scheme: light dark;
+  --bg:   var(--obsidian-bg,   light-dark(#ffffff, #0e1014));
+  --text: var(--obsidian-text, light-dark(#16161a, #e7e9ec));
+}
+```
+
+Today this CSS already follows OS light/dark via `prefers-color-scheme`. Once the plugin ships theme injection, the snapshot reflects the user's exact Obsidian theme — including custom themes and snippets — and your variable fallbacks resolve to those values automatically. No code change needed on the HTML side.
+
+## Assets — vault paths do NOT cross into the iframe
+
+The iframe has no base URL pointing into the vault. Obsidian themes, snippets, and `attachments/...` images don't reach the iframe.
+
+| Pattern | Works? |
+|---|---|
+| `<img src="attachments/foo.png">` | No — fails silently |
+| `<img src="data:image/png;base64,...">` | Yes — fully self-contained |
+| `<img src="https://example.com/foo.png">` | Yes — CORS permitting |
+| Inline `<svg>...</svg>` | Yes — best for icons / diagrams |
+| `<link rel="stylesheet" href="https://cdn...">` | Yes — HTTPS only |
+
+Rules of thumb:
+
+- Small graphics & icons → inline SVG or `data:` URL
+- Photos / large images → upload to a host (R2, CDN) and reference HTTPS
+- Fonts → system stack, or HTTPS CDN
+- Never reference `attachments/` or any vault path — the iframe can't see them
+
+## What works
+
+- HTML / CSS (grid, `light-dark()`, custom properties, animations, gradients, SVG with CSS animations)
+- JavaScript (ES2020+, fetch with CORS, Promises, DOM events, requestAnimationFrame, Canvas 2D)
+- Forms (`allow-forms` is set; intercept `submit` if you don't want navigation)
+- `window.parent.postMessage(msg, '*')` — works even with opaque origin
+- External HTTPS resources (images, fonts on CDNs, fetch APIs that allow CORS)
+- Anchor links (`#section`) and the History API — Blob URL preserves both
+
+## What's blocked
+
+- `localStorage`, `sessionStorage`, `IndexedDB` — `SecurityError`
+- `document.cookie` — throws or silently no-ops
+- Reading `window.parent.*` — cross-origin (postMessage still works)
+- Service workers, geolocation, clipboard, notifications, most permission-gated APIs
+- Top-level navigation from inside the iframe (no `allow-top-navigation`)
+- Vault-relative URLs (see Assets above)
+
+## Linking from markdown to HTML
+
+Wikilinks to `.html` files need the explicit extension:
+
+```markdown
+See: [[my-doc.html]]
+```
+
+`[[my-doc]]` won't resolve to `.html` in stock Obsidian.
+
+## Embed sizing
+
+```markdown
+![[doc.html|width=600 height=400]]
+```
+
+Sets `--html-docs-width` / `--html-docs-height` on the embed container. Default embed height is ~600px; tab views fill the pane.
+
+## Pitfalls (skip the turn cost)
+
+- **Theme scripts that read `window.parent`** — always throw under this plugin's sandbox. Don't write them.
+- **Images via `attachments/foo.png`** — won't resolve. Inline as data URL or use HTTPS.
+- **`localStorage` / cookies for state** — blocked. Use URL hash or postMessage to parent.
+- **Hard-coding a palette when Obsidian tokens are available** — defeats the contextual fit. Use `var(--obsidian-*)` with `light-dark()` fallbacks.
+- **Assuming `prefers-color-scheme` == Obsidian theme** — usually true, sometimes not. Once the plugin ships theme injection, this is fully resolved.