HTML Embeds

Make long agent docs
easier to understand.

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.

DimensionMarkdownHTMLMarkside 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.

  1. Install Markside.

    Add Markside to Chrome, then enable Allow access to file URLs in its extension settings.

    Open the Chrome Web Store
  2. 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
  3. 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 Embed

    Comment in Markside, then send your review to the agent.

Explore more with Markside.