HTML Viewer — Obsidian Community Plugin

Render .html files directly inside Obsidian. Sandboxed by default — toggle Scripts ON for games, D3/ECharts visualizations, and interactive documents.

---

Installation

Manual (from this repo)

Copy the html-viewer/ folder into <vault>/.obsidian/plugins/, then enable it in Settings → Community Plugins.

.obsidian/plugins/html-viewer/
├── manifest.json
├── main.js
├── styles.css
└── README.md

Restart Obsidian or reload plugins (Ctrl+P → "Reload plugins").

---

Usage

1. Place any .html or .htm file in your vault
2. Click it in the file explorer → opens in HTML Viewer
3. Use the toolbar:

Button	Function
Source / Rendered	Toggle between raw HTML source and rendered view
Scripts: OFF / ON	Enable/disable JavaScript execution (default: OFF)
Refresh	Reload the file from disk

Or via command palette: Open HTML viewer.

---

Modes

Safe Mode (Scripts OFF — default)

• All <script> tags removed
• Inline event handlers (onclick, onerror, etc.) stripped
• javascript: pseudo-URLs neutralized
• iframe sandbox: allow-same-origin

Use for: static pages, untrusted HTML, document previews.

Interactive Mode (Scripts ON)

• JavaScript execution enabled
• Event handlers and javascript: links still stripped
• Auto-focus injected so keyboard games work immediately
• iframe sandbox: allow-scripts allow-same-origin

Use for: Canvas games, D3.js / ECharts / Three.js visualizations, interactive tutorials, and any trusted local HTML with scripts.

---

Supported Features

Feature	Safe Mode	Interactive Mode
HTML + CSS	✅	✅
Images, video, audio	✅	✅
External CSS/images (CDN)	✅	✅
Anchor links (#section)	✅	✅
<canvas> 2D / WebGL	—	✅
JavaScript applications	—	✅
External <script src="...">	—	✅
Keyboard input (games)	—	✅
localStorage	—	⚠️ session-only*
File auto-refresh (external edit)	✅	✅

* localStorage works within a session but resets on refresh because each render uses a new Blob URL.

Blocked by Design

These are intentionally unavailable for security, even in Interactive Mode:

• Form submission (no allow-forms)
• Popup windows (no allow-popups)
• File upload (<input type="file">)
• Top-level navigation (no allow-top-navigation)
• Access to window.parent / Obsidian DOM
• Inline event handlers — always stripped
• javascript: URLs — always neutralized

---

Smart Features

• Dedup: clicking the same HTML file twice focuses the existing tab instead of opening a duplicate
• Auto-refresh: edits to the HTML file in an external editor are picked up automatically
• Delete handling: if the HTML file is deleted, the view shows a clear message
• Race-condition guard: rapid file switching won't cause stale renders
• Blob URL cleanup: memory properly released when closing tabs or switching files

---

Compatibility

• Desktop: Windows, macOS, Linux — full support
• Mobile: iOS / Android — supported (isDesktopOnly: false). Keyboard auto-focus is desktop-only; tap the game area for touch controls
• Obsidian ≥ 1.0.0
• Themes: uses Obsidian CSS variables — adapts to any theme

---

Security Model

┌──────────────────────────────────────────┐
│            Obsidian Window               │
│  ┌────────────────────────────────────┐  │
│  │  Toolbar: [Source] [Scripts] [↻]   │  │
│  └────────────────────────────────────┘  │
│  ┌────────────────────────────────────┐  │
│  │  Sandboxed iframe                  │  │
│  │  ┌──────────────────────────────┐  │  │
│  │  │  Stripped: <script>,         │  │  │
│  │  │  on*=, javascript:           │  │  │
│  │  │  Blocked: forms, popups,     │  │  │
│  │  │  file access, navigation     │  │  │
│  │  └──────────────────────────────┘  │  │
│  └────────────────────────────────────┘  │
└──────────────────────────────────────────┘

Double-layer protection: regex sanitization at the content level + browser sandbox at the iframe level.

---

Version History

Version	Changes
1.2.0	CSS namespace prefix (html-viewer-); race-condition guard; auto-refresh on external edit; delete handling; mobile-ready manifest
1.1.2	Strip javascript: pseudo-URLs
1.1.1	Auto-focus iframe for keyboard games
1.1.0	Scripts ON/OFF toggle
1.0.2	Dedup: same file → focus existing tab
1.0.1	Blob URL instead of srcdoc (fixes anchor navigation); flex layout
1.0.0	Initial release

---

License

MIT