HTML Embeds
Make long agent docs
easier to understand.
- Keep your document clean and token-efficient in Markdown.
- See complex ideas clearly with interactive HTML visuals.
- Comment on a visual and send feedback to your agent.
The best of both worlds.
In The unreasonable effectiveness of HTML, Thariq Shihipar makes a compelling case for using HTML to make agent-written documents more visual and easier to understand. I couldn’t agree more.
But most plans, specs, and notes are text, with visuals often expressible as tables or Mermaid diagrams. Many prefer Markdown because it’s lightweight, token-efficient, and supports quick, simple edits.
Markside HTML Embeds bring both together: keep Markdown and add interactive HTML where it helps.
| Dimension | Markdown | HTML | Markside HTML Embed |
|---|---|---|---|
| Human edit | 🟢 Easy to edit | 🟠 Edit around HTML tags | 🟢 Edit Markdown text |
| Agent read | 🟢 Token-efficient text | 🟠 More tokens for markup | 🟢 HTML read on demand |
| Comprehensibility | 🟠 Text and diagrams | 🟢 Rich visual explanations | 🟢 Visuals beside text |
| Interactivity | 🟠 Mostly static | 🟢 Interactive prototypes | 🟢 Interactive embeds |
| Markdown editor viewing | 🟢 Renders Markdown | 🟠 Editor support varies | 🟢 Renders Markdown |
| Browser viewing | 🟠 Needs a viewer | 🟢 Opens in browser | 🟢 Opens in browser |
What about inline HTML?
Markdown supports inlining HTML directly, and Markside renders it too. Inline HTML is handy for small additions, such as a <details> block. But larger visuals can fill your Markdown with tags and styles, making the source harder to read and edit and adding tokens for agents. HTML Embeds keep that code in a separate file while displaying the visual in your document. Use whichever fits: Markside supports both.
Get started in three steps.
-
Install Markside.
Add Markside to Chrome, then enable Allow access to file URLs in its extension settings.
Open the Chrome Web Store -
Install the Markside skill.
Add the Markside skill to your agent. It knows how to create HTML Embeds.
npx skills add ericjy/markside --skill markside -g -
Ask your agent to explain.
Ask your agent to explain a topic with an HTML Embed. It will create the files and open them in Markside for review.
/markside Explain the feature in spec.md with HTML EmbedComment in Markside, then send your review to the agent.