Guide
Claude Code HTML instead of Markdown: write it, open it, share it
Updated 30 October 2026
Ask Claude Code for an HTML file instead of Markdown and you get a page with tables, diagrams and tabs, which Anthropic’s post “The unreasonable effectiveness of HTML” argues people are much more likely to read. Open it locally with open report.html. To show it to others, publish it to ashare.net from the same session and choose who opens the link: everyone at your company, specific people by email, or anyone with a password. Their comments come back to Claude Code, which fixes the page at the same link.
What Anthropic’s post says
The post is by Thariq Shihipar of the Claude Code team, published on 20 May 2026 as his personal take. His starting point: a Markdown file of more than about a hundred lines is hard to read, and he rarely edits these files by hand any more, he asks Claude to. So he switched to HTML for almost everything, and sees others on the team doing the same. The reasons he gives:
- Density. HTML holds tables, SVG diagrams, code, layouts, images and interactive controls, so Claude doesn’t fall back on tricks like estimating colors with Unicode characters.
- Readability. Tabs, links and illustrations make a long document easy to navigate, and the page can be responsive on a phone.
- Sharing. Browsers don’t render Markdown well, so it travels as an email attachment. An HTML file, once uploaded, is a link anyone opens.
- Two-way interaction. Sliders, knobs and a “copy as prompt” button let the reader tune something and paste the result back into Claude Code.
The use cases in the post: specs and plans (several approaches side by side, then an implementation plan), code review (the diff with margin notes color-coded by severity), design prototypes with tunable parameters, reports and explainers, and throwaway editors for one dataset that end with an export button. On cost, the post admits Markdown often uses fewer tokens and finds the better output worth it. The examples are in github.com/anthropics/html-effectiveness.
HTML or Markdown
| The document | Format | Why |
|---|---|---|
| A plan, review, report or incident write-up that people read once | HTML | Layout, diagrams and tabs keep a long page readable. |
| Options to compare, a chart, a timeline | HTML | Side by side and visual, with no screenshots. |
| A README, CLAUDE.md or a decision record in the repository | Markdown | It lives in git, people read it in diffs and edit it by hand. |
| Notes nobody but the agent reads | Markdown | Fewer tokens, and nobody needs the layout. |
ashare.net publishes both. A Markdown file renders as a styled page, so a doc that has to stay in Markdown still gets a link.
Ask Claude Code for an HTML report
The post’s advice is to start simple, “make an HTML file”, and say what the page is for and who reads it. Name a path, so the file lands where you can find it:
Read the rate limiter code and write a single HTML explainer to reports/rate-limiter.html: a diagram of the token-bucket flow, the 3–4 key snippets annotated, and a “gotchas” section at the bottom. Optimize it for someone reading it once.A few more that work:
- “Write this week’s status report as one HTML file in
reports/: a summary at the top, the details in collapsible sections.” - “Turn the plan into an HTML page with the three options side by side and a one-line trade-off under each.”
- “Review this branch and render the diff as HTML with notes in the margin, colored by severity.”
Ask for SVG when you want diagrams. Keep it to one file, or ask for a folder with an index.html when the report needs several pages: ashare publishes a folder as a small site where links between pages, CSS and images work.
Open the HTML file on your computer
An HTML file opens in any browser. Double-click it, ask Claude Code to open it, or run:
open reports/rate-limiter.html # macOS
xdg-open reports/rate-limiter.html # Linux
start reports\rate-limiter.html # WindowsA file you downloaded from claude.ai opens the same way. A local file works for you alone: its link is a path on your disk, and sending the file means sending an attachment again.
Claude Code’s own Artifacts
Claude Code can publish a page itself when you ask it to “make an artifact”. Per Claude Code’s docs, the page goes to a private URL on claude.ai, each publish is a version at the same link, and you share it from the page header: within your Claude organization on Team and Enterprise plans, or as a public link. Artifacts come with Pro, Max, Team and Enterprise plans.
Three limits matter when you share one. An artifact is one self-contained page, with external images blocked. People who open the public link can’t see or add comments. And artifacts are off by default in claude -p, the Agent SDK and the GitHub Action. If everyone who reads your pages is in the same Claude Team or Enterprise organization, Artifacts cover it. For readers outside it, see how to share a Claude Code artifact outside your organization.
Show it to the right people
Connect ashare to Claude Code once:
$ claude mcp add -s user --transport http ashare https://ashare.net/mcpRun /mcp, pick ashare and sign in in the browser with a code from your email; there is no key to copy. The Claude Code plugin adds a skill for the whole loop and asks who should see a document before it publishes. Then ask:
Publish reports/rate-limiter.html to ashare and share it with the companyA new document is private: only you open it. You choose who else gets in:
- Your company. Everyone who signs in with an email on your company domain.
- Specific people. Up to 100 emails per document; each one gets a letter with the link.
- A password. “Make it public with a password, expiring in 7 days” lets in anyone with both the link and the password, until that date.
Readers sign in with a 6-digit code from their email, or with Google or Microsoft, and create no account. Anyone else who opens the link can ask you in. For private and company documents you see who opened it and when.
Get the comments back into Claude Code
- Readers select text and comment. You get an email when there is something new.
- Ask Claude Code: “Go through the comments on the rate limiter report.” It lists the open threads with the quoted text.
- It edits the page, publishes a new version at the same link, replies in each thread with what it changed and resolves it.
- Send readers the link with
?v=2&diff=1: they see version 2 with the changes since version 1 marked.
The threads live on ashare.net, not in the session, so tomorrow’s session, or Codex, picks them up where this one stopped.
ashare.net: your agent publishes HTML or Markdown and you choose who opens it: your company, specific emails or a password. Readers comment, the agent fixes the document.
Connect your agent