Agentic HTML Visual Editor

English | 日本語

Agentic HTML Visual Editor is a WYSIWYG editor for .html files in VS Code. AI agents and people read and write the same plain HTML file: an agent writes the document, and you edit and review it without touching the markup.

Edit an HTML file as a document. Review comments by people and AI agents live in the file itself.

📑 Table of Contents

• 📑 Table of Contents
• ✨ Why This Extension
• 🚀 Getting Started
• 🤖 Agent Skill
• 👀 Features at a Glance
• 🧩 Features in Detail
  • 🔠 Formatting and Blocks
  • ✅ Lists
  • 🧮 Tables
  • 🔽 Collapsible Sections
  • 💡 Alerts
  • 💬 Review Comments
  • 🔄 Change Review
  • 🔗 Links and Images
  • 📊 Mermaid Diagrams
  • 🔍 Find and Replace
  • 🧭 Sidebar
  • 📋 Clipboard
  • 💾 Safe Saving
  • ⏪ Undo and Recovery
  • 📄 PDF Export
  • 🧰 Toolbar and Menus
  • 🌐 Languages and Accessibility
• ⚡ Keyboard Shortcuts
• 💻 Requirements
• 🚫 Known Limitations
• 📝 Release Notes
• 📄 License

✨ Why This Extension

Use it for design notes, research reports, and task lists that AI agents and people edit and review together.

• For agents: writing small, correct HTML is enough, which keeps their output short.
• For people: a readable view to edit and review in, with no HTML knowledge needed.
• For the file: no intermediate format and no sidecar files. The HTML is complete and portable on its own, review comments included.

A typical round trip:

1. An AI agent writes the deliverable as an .html file. The Agent Skill teaches it the markup this editor expects.
2. You open the file in the WYSIWYG view, edit it, and leave review comments.
3. The agent reads your edits and comments straight from the HTML and answers in the same threads.

🚀 Getting Started

1. Install Agentic HTML Visual Editor from the VS Code Marketplace, then open an .html file. It opens in the standard text editor as usual; the extension does not take over the default editor.
2. Click Open in WYSIWYG in the editor title bar, or run Visual Editor: Open in WYSIWYG from the Command Palette. The view takes the place of the tab in the same editor group.
3. Edit, then save with Ctrl+S (Cmd+S on macOS). Undo and redo use the usual keys and keep working across saves.
4. To see the HTML again, click Open in HTML in the editor title bar.

To open .html files in the view by default, run Reopen Editor With… and choose Configure default editor for '*.html'….

For a new, empty file, choose Create HTML Skeleton and Open in the view to write the basic HTML structure and start editing.

🤖 Agent Skill

This repository provides an Agent Skill that teaches an AI agent how to write HTML for this editor and how to work with its review comments. Install it with:

npx skills add Ymmy833y/Agentic-HTML-Visual-Editor

The command installs the skill agentic-html-visual-editor-authoring. The scripts in it that list the comments of a document and check their markup (list_comments.py and check_comments.py) require Python 3.11 or later.

👀 Features at a Glance

🧩 Features in Detail

🔠 Formatting and Blocks

• Apply bold, italic, strikethrough, inline code, and links from the toolbar. All but strikethrough are also in the floating menu over a selection, and bold, italic, and links have keyboard shortcuts.
• With only a caret, toggle bold, italic, strikethrough, or inline code for the next text you type. Clear Formatting removes inline formatting from a selection and block styles when all of the block's text is selected; links remain.
• Convert between headings 1–6, paragraphs, and blockquotes from the block type menu. A separate toolbar button toggles code blocks.
• Blockquotes and alerts can contain headings, paragraphs, lists, and code blocks. Backspace at the start of the first text block moves it out of the quote.
• Type Markdown-style triggers at the start of a block, such as ## for a heading or - for a list. See Keyboard Shortcuts.
• Press Enter on the empty last line of a code block to leave it and continue in a new paragraph.
• In a code block, Tab inserts four spaces at the caret or indents selected lines; Shift+Tab removes one level of indentation.
• A bundled stylesheet gives plain HTML a modern look, and style attributes written in the file take precedence over it.

✅ Lists

• Create bulleted and numbered lists, switch between them, or turn them back into paragraphs.
• Tab nests an item under the previous one, and Shift+Tab moves it back out; at the top level it becomes a paragraph. Enter on an empty item leaves the list.
• Converting a selection changes every block it holds, and leaves tables, code blocks, and other structures it only spans where they are.
• A conversion next to a list of the same type joins that list and continues its numbering.

🧮 Tables

Right-click a cell for the table actions.

• Insert a table from the grid picker.
• Add and delete rows and columns, and switch header rows and columns, with th and scope kept correct.
• Merge and split cells, including a rectangular range picked with Shift+click.
• Drag a column border to resize it, in px or %.
• Tab and Shift+Tab move between cells; Tab in the last cell adds a row. At a cell's last or first line, ArrowDown and ArrowUp move to the cell below or above, or out of the table at its edge. Code blocks and lists keep their own Tab behavior inside cells.
• The table actions live in a context menu; Shift+F10 or the Menu key opens it from the keyboard.

🔽 Collapsible Sections

• Insert a <details> / <summary> section from the toolbar. It opens and closes in the view, and its open state is saved to the HTML.
• Click the marker to open or close it; clicking the title text edits the title. Enter in the title moves the caret into the body.

💡 Alerts

• Note, Tip, Important, Warning, and Caution blockquotes are stored as <blockquote data-alert="…">. The view draws the label, icon, and color without writing them into the file.
• Choose one from the block type menu, or type >note, >tip, >important, >warning, or >caution and a space at the start of a block.
• An unknown alert type is kept in the file and shown as a plain quote.

💬 Review Comments

A thread between an AI agent and a person, stored in the HTML itself.

• <comment> annotations live in the HTML itself, so any reader, human or AI, can follow the whole thread from the markup.
• Select text and add a comment from the toolbar or floating menu. Click the highlighted text, or press Alt+Enter with the caret inside it, to open its thread.
• Write the body and the replies with the document's formatting: inline styles, links, headings, lists, code blocks, tables, and the other blocks. The toolbar, the floating menu, and the keyboard shortcuts work inside the comment fields.
• Drag the popup's right edge to resize it. The width stays within the view and carries over to other comments and other files.
• Add, edit, and delete the body and the replies. Each entry records its author and time and shows an avatar in the author's color, so entries by people and by AI agents are easy to tell apart.
• Mark a thread as resolved; resolved threads recede visually.
• Editing or deleting an entry that an AI agent wrote asks for confirmation first.
• Step to the previous or next thread from the popup.
• Editing or deleting text around a comment preserves its hidden body and replies.

🔄 Change Review

• Agents mark proposed changes in the HTML with <ins> and <del>, or data-change="ins" / data-change="del" on whole elements. Editing in the view does not automatically create these marks.
• Insertions and deletions have distinct highlighting. Click a mark, choose it in the sidebar, or press Alt+Enter with the caret inside it to open its author, time, and Accept / Reject actions.
• An adjacent deletion and insertion are reviewed as one replacement when both are marked as AI-authored or both as human-authored. Accepting keeps the new text; rejecting restores the old text.
• The sidebar's Changes tab offers Accept All and Reject All. Each decision, including a decision on every change, can be undone in one step.

🔗 Links and Images

• Insert and edit links and images in dialogs. Enter confirms and Esc cancels.
• Image width and height accept px or %; a number without a unit is treated as px.
• Ctrl+click (Cmd+click on macOS) follows a link, so a plain click keeps the link text editable.
• Relative file links open in VS Code tabs. The target must be inside the document's workspace folder, or its own directory when outside a workspace. Resolution starts from the HTML file's directory, then tries the workspace folder if the file is missing.
• A link starting with /, such as /docs/notes.html, starts from the document's workspace folder. It requires a workspace and never refers to the operating system's root directory.

📊 Mermaid Diagrams

Diagrams follow the VS Code theme, shown here in the dark theme.

• <pre class="mermaid"> and <pre><code class="language-mermaid"> blocks render as diagrams in the light or dark theme.
• Insert a diagram from the toolbar, or click an existing one to edit its source in a dialog.
• The file keeps the source, never the drawing. Invalid syntax shows an error card, and the source stays editable.
• Zoom from 50% to 400% with the buttons shown over a diagram or Ctrl+wheel (Cmd+wheel on macOS). Reset returns to 100%. Zoom does not change the HTML.

🔍 Find and Replace

• Ctrl+F opens a find panel that highlights every match and shows your position, such as 2 of 7.
• Enter and Shift+Enter move to the next and previous match; Esc closes the panel and leaves the caret on the current match.
• Toggle match case and whole word. Opening the panel with text selected starts with that text.
• Find searches the visible text and comment IDs: a query in a comment's id jumps to that comment and opens its thread.
• Highlighting never changes the document or the saved HTML.
• Ctrl+H (Cmd+Option+F on macOS), or the toggle at the left of the panel, shows a replace field. Enter there or Replace replaces the current match and moves to the next; Replace All replaces every match at once. Each is one step to undo, and the replacement takes the formatting of the first character it replaces.
• Replace leaves comment IDs alone, and skips a match that runs across the edge of a comment's annotated text, so a comment never gains or loses text you did not mean it to.

🧭 Sidebar

• The sidebar at the left edge has Headings, Comments, and Changes tabs, each in document order. Headings show their level; comment threads show a dot in the original author's color or a check when resolved.
• Choose an item to jump to it. The toolbar button at the far left opens and closes the sidebar.
• Drag the sidebar's right edge to resize it. Whether it is open and how wide it is carry over to every file you open next.
• In a narrow sidebar, the tabs show icons with tooltips. Arrow keys move between tabs and between items; Enter or Space opens an item.

📋 Clipboard

• Copy and cut write clean HTML without comment metadata; only the annotated text remains.
• Pasting from Office, Google Docs, or a browser drops their markers and computed styles, and keeps only the styles that carry meaning: text and background colors, alignment, and table and image sizes. Ctrl+Shift+V pastes plain text.
• Copy as HTML copies the selection, or the whole body when nothing is selected.
• Hover a code block to show its copy button, which copies the code as plain text.

💾 Safe Saving

• Lines you did not edit stay exactly as they are on disk, including whitespace, attribute quotes, tag case, and void elements.
• If the file changes on disk while you edit, saving merges both sides line by line.
• If the same file has unsaved changes in a text editor tab, save that tab before saving the visual editor.
• If the changes conflict, compare previews or the HTML and choose the file's version, the visual editor's version, or both for each conflict. Canceling leaves your edits unsaved.
• Event-handler attributes and unsafe URLs are neutralized only inside the view and are written back as they were.
• Files use VS Code's selected encoding when opened and are saved as UTF-8. If the current encoding cannot read the file correctly, the view asks you to use Reopen with Encoding in the text editor first.

⏪ Undo and Recovery

• Undo and redo cross save points and put the caret back where the change was.
• Visual undo, redo, and Revert File remain available while a text editor tab has unsaved changes; that tab's edits stay intact.
• Unsaved edits backed up by VS Code can be restored after a window reload or restart.

📄 PDF Export

• Click Export as PDF in the toolbar, or run Visual Editor: Export as PDF from the Command Palette, then choose where to save. The PDF includes the current unsaved edits without saving the HTML.
• Pages use A4 portrait, a white background, and the light theme. Tables, images, and Mermaid diagrams are included. Closed collapsible sections show only their titles; comments show only their annotated text.
• Text is set in the bundled BIZ UDPGothic and BIZ UDGothic fonts, so you can select, copy, and search it in a PDF reader. Backgrounds, borders, images, diagrams, and list markers stay in the page image.
• Text that the fonts do not cover, such as emoji, Hebrew, and Hangul, and text that a style makes transparent, transformed, or shadowed, stays in the image and cannot be selected or searched.
• Remote images may be omitted if their server does not allow cross-origin loading (CORS).
• Web, email, and document-anchor links remain clickable. File links are resolved with the editor's rules and written relative to the PDF's save location when that location can reach them.
• Accept or reject all change marks before exporting.

🧰 Toolbar and Menus

• The toolbar follows the caret and shows the current block type and formatting.
• A floating menu appears over a selection, and the save button shows a dot when there are unsaved changes.

🌐 Languages and Accessibility

• The UI is in English and Japanese, following VS Code's display language.
• Both the document and the editor UI follow the VS Code theme: light, dark, and high contrast.
• The toolbar, menus, dialogs, and comment popup work with the keyboard alone, with a visible focus ring; Alt+F10 moves the focus to the toolbar.

⚡ Keyboard Shortcuts

On macOS, use Cmd in place of Ctrl and Option in place of Alt.

Typing these at the start of a block formats it:

💻 Requirements

• VS Code 1.90 or later.
• Desktop VS Code on Windows, macOS, and Linux, VS Code for the Web (such as vscode.dev), virtual workspaces, untrusted workspaces, and Remote Development.

🚫 Known Limitations

• Scripts never run, and external CSS or JavaScript is never loaded. Forms are shown but cannot be submitted.
• A document does not open in the view when its body contains script, iframe, object, embed, noscript, link, style, base, or meta, or when it does not have exactly one <body> start tag and one end tag. A dialog explains why and offers the text editor.
• The extension has no configurable settings.
• Clearing formatting requires a selection.
• Formatting and navigation shortcuts cannot be reassigned through extension settings. GNOME uses Alt+F10 to maximize windows, so it does not reach the view. On macOS, Option+F10 and Shift+F10 may require Fn.
• Multiple visual editor tabs for the same file are not supported.
• Moving text by dragging it within the document, or dropping external content into it, is not supported.
• Parsing drops a few things the view cannot hold: the newline right after <pre>, the second and later copies of a repeated attribute, stray end tags, <body> and <html> tags inside the body, and frame / frameset. The file changes only where you edit the lines that contain them.
• Out of scope: formatting HTML source, converting to or from Markdown, real-time co-editing, telemetry, and editing file types other than HTML.

📝 Release Notes

See CHANGELOG.md.

📄 License

MIT. The third-party software bundled with the extension is listed in THIRD_PARTY_NOTICES.md.