🎨 HTML Studio

The HTML Editor & Viewer for the AI era.

Stop opening HTML files one by one. HTML Studio turns any folder into a browsable, editable, auto-saving document hub — in one command.

---

Why HTML Studio?

AI coding tools (Claude Code, Cursor, Copilot) generate HTML artifacts constantly — reports, dashboards, cover images, presentations. But then you're stuck:

• Opening each file manually in a browser
• No way to edit without source code
• No auto-save, no version history
• Files scattered across directories

HTML Studio solves this. One command, all your HTML in one place, instantly editable.

---

Quick Start

Option 1: Download executable (recommended, zero install)

1. Go to Releases
2. Download HTMLStudio-<version>-macos-arm64.dmg (Apple Silicon Mac) or HTMLStudio.exe (Windows)
3. On Mac, open the notarized DMG and drag HTML Studio to Applications; on Windows, double-click the EXE

Option 2: Double-click launch (from source)

1. Download the project (ZIP or git clone https://github.com/louisecxqiu-glitch/html-doc-center.git)
2. Double-click 启动 HTMLStudio.command (Mac) or 启动 HTMLStudio.bat (Windows)
3. Browser opens automatically → start using

First run auto-installs the dependency (aiohttp), requires internet.

Option 2: Command line

git clone https://github.com/louisecxqiu-glitch/html-doc-center.git
cd html-doc-center
pip install aiohttp
python3 server.py --open-browser
# → http://localhost:9901

Or as a Claude Code Plugin:

/plugin install htmlstudio@claude-plugins-official

---

Features

Feature	Description
📁 Directory tree	Auto-discovers all HTML/MD files, searchable sidebar
✏️ Click to edit	Zero-config inline editing with toolbar injection
💾 Smart auto-save	2s idle → snapshot; close → overwrite / save-as / discard
🔍 Markdown support	Built-in MD editor with live preview
⭐ Favorites & sort	Bookmark files, sort by time or name
🔄 Live refresh	10s polling with ETag signatures (99.99% zero-traffic)
📂 Multi-root	Configure multiple scan directories via settings UI
🖱️ Drag & drop	Move files between directories
🔒 Path-safe	All writes validated against scan_roots whitelist

---

v3.0: Three-Mode Editing + AI Text Editing

v3.0 introduces a professional three-mode editor kernel, AI-assisted text editing, and version history.

Three Editing Modes

When you open an HTML file, you get three editing modes:

Mode	Engine	Best for
🎨 Design	GrapesJS	Visual editing: drag components, edit properties, see layout
📝 RichText	ProseMirror	Text-focused editing: bold, italic, lists, links, headings
</> Source	CodeMirror 6	Direct HTML/CSS editing with syntax highlight, search

Switch modes with the top toolbar buttons or keyboard shortcuts (Alt+D/R/S).

Component Library (Blocks)

The left sidebar has 14 draggable components:

• Basic: Heading, Paragraph, Text, Button, Link, Divider, Quote, Table
• Layout: Container, 2-Columns
• Media: Image, Video
• Lists: Bullet List, Numbered List

Property Panel

The right sidebar shows two tabs:

• Style: Typography, Layout, Background, Border, Effects
• Props: Element ID, classes, attributes

AI Text Editing

1. Select text in Design or RichText mode
2. Click the ✨ AI Edit button (or the floating button near your selection)
3. Enter your instruction (e.g., "Make this more concise", "Translate to Chinese")
4. Review the diff preview (added/removed highlights)
5. Click Accept, Reject, or Regenerate

• AI results are never auto-applied — you must review and accept
• Only your selected text is sent to AI (never the full document)
• Each AI accept creates one undoable action (Ctrl+Z to revert)

Configuring AI Providers

Edit ~/.codebuddy/html-doc-center/config.json and add an ai section:

{
  "ai": {
    "default_provider": "openai",
    "providers": {
      "openai": {
        "type": "openai-compatible",
        "base_url": "https://api.openai.com/v1",
        "model": "gpt-4o-mini",
        "api_key": "sk-..."
      },
      "anthropic": {
        "type": "anthropic",
        "base_url": "https://api.anthropic.com/v1",
        "model": "claude-sonnet-4-20250514",
        "api_key": "sk-ant-..."
      },
      "ollama": {
        "type": "openai-compatible",
        "base_url": "http://localhost:11434/v1",
        "model": "llama3.1",
        "api_key": "ollama"
      }
    }
  }
}

Or use environment variables (e.g., "api_key_env": "OPENAI_API_KEY").

Version History

HTML Studio automatically creates version snapshots:

• Before AI edits (pre-ai)
• Before version restore (pre-restore)
• When you manually save (pre-overwrite / manual)

Each version records a content hash, timestamp, and reason tag. Access version history through the History button in the toolbar.

Complex Page Protection

Pages with scripts, framework mount points (React/Vue), or excessive CSS rules are automatically detected as "complex" and default to Source mode to prevent visual editing from altering structure. You can opt into visual editing with the "Enable anyway" button.

Keyboard Shortcuts

Shortcut	Action
Ctrl+Z / Cmd+Z	Undo
Ctrl+Y / Cmd+Shift+Z	Redo
Alt+D	Switch to Design mode
Alt+R	Switch to RichText mode
Alt+S	Switch to Source mode
Ctrl+F (Source)	Search in code

---

---

Claude Code Integration

HTML Studio works as a Claude Code Plugin with MCP support:

/hotpage ./report.html     # Open file in HotPage
/hotpage serve ./outputs   # Serve a directory

When Claude Code generates HTML, it automatically opens in HTML Studio for preview and editing.

MCP Tools

Tool	Description
hotpage_open	Open a specific file
hotpage_status	Check if server is running
hotpage_serve	Start serving a directory
hotpage_list	List all discovered files

---

Architecture

┌─────────────────────────────────────────┐
│  Python (aiohttp) — single process      │
│  ├─ /api/tree → directory tree JSON     │
│  ├─ /api/file → serve HTML with         │
│  │              saver-runtime.js inject  │
│  ├─ /api/save → overwrite / save-as     │
│  └─ /api/settings → config CRUD         │
├─────────────────────────────────────────┤
│  saver-runtime.js (injected into iframe)│
│  ├─ contentEditable toolbar             │
│  ├─ 2s idle → auto-snapshot             │
│  ├─ postMessage ↔ parent frame          │
│  └─ close → 3-option dialog             │
├─────────────────────────────────────────┤
│  web/app.js — sidebar + iframe viewer   │
└─────────────────────────────────────────┘

Zero dependencies beyond aiohttp. No npm, no webpack, no build step.

---

Configuration

Config stored at ~/.codebuddy/html-doc-center/config.json:

{
  "scan_roots": [
    {"path": "/Users/me/reports", "enabled": true},
    {"path": "/Users/me/outputs", "enabled": true}
  ]
}

Or configure via the in-app Settings panel (⚙️ button).

---

Comparison

	HTML Studio	mcp-html-artifacts-preview	File Browser
Editing	✅ Inline edit + toolbar	❌ View only	❌ No
Auto-save	✅ 2s snapshot + 3-option	❌ No	❌ No
Persistence	✅ Files stay on disk	❌ Session-only	✅ Yes
Zero-config	✅ One command	✅ MCP config	⚠️ Docker
Claude Code	✅ Plugin + MCP	✅ MCP only	❌ No
Markdown	✅ Built-in	❌ No	❌ No

---

Development

# Run the local development server without opening a browser automatically
python3 server.py --no-open-browser

# Then open http://127.0.0.1:9901 in your browser

# Run tests
python3 -m pytest tests/

Build distributable apps

python3 -m pip install -r requirements-build.txt
python3 build.py

On Apple Silicon macOS, the signed and notarized release command is:

python3 scripts/release_macos.py

See docs/macos-release.md for the one-time Apple certificate and GitHub Secrets setup.

WeChat article formatter

将 Markdown 教程转换成带苹果式内联样式、可直接复制到微信公众号编辑器的单文件 HTML：

python3 tools/wechat_formatter.py path/to/article.md --open

图片路径按 Markdown 文件所在目录解析；脚本会把本地图片内嵌到 HTML。需要指定输出路径时使用 --output，覆盖已有输出时使用 --force。

See CONTRIBUTING.md for guidelines.

---

License

MIT © Louis Jobs 2026