I have been building a slightly different solution to the same problem. So far I’m pretty happy with the results and I have enough returning users that I think others are too (https://sdocs.dev/analytics).

I’ve built SmallDocs (https://sdocs.dev; Show HN: https://news.ycombinator.com/item?id=47777633).

SDocs is cli (`sdoc file.md`) -> instantly rendered Markdown file in the browser

When you install the cli it gives you the option to add a note in your base agent file (`~/.claude/CLAUDE.md`, etc.). This means every agent chat knows about SDocs and you can say “sdoc me the plan when you’re done with it” and the file will pop open instead of you having to find that terminal session to know it’s done.

Going browser first means you’re not required to install anything to get a great experience.

Despite being in the browser, the content of SDocs rendered Markdown files remain entirely local to you. SDoc urls contain your markdown document's content in compressed base64 in the url fragment (the bit after the `#`):

https://sdocs.dev/#md=GzcFAMT...(this is the contents of your document)...

The url fragment is never sent to the server (see https://developer.mozilla.org/en-US/docs/Web/URI/Reference/F...: "The fragment is not sent to the server when the URI is requested; it is processed by the client").

The sdocs.dev webapp is purely a client side decoding and rendering engine for the content stored in the url fragment.

This also means you can share your .md files privately by sharing the url.

To go a bit deeper towards the HTML side of things I’ve added tagged code blocks that the agent is given documentation on how to use. Eg ```chart or ```mermaid (for mermaid diagrams). These then become interactive elements on the page (mermaid is best example of this currently)

I hadn't considered HTML and I'm definitely going to try this.

The most important thing is that I can run static analysis on a structured format. This is important even for my spec documents. I can write data fields and have static analysis analyze it. For example, to confirm database fields match across various spec documents, etc.. The static analysis is also why you use JSON/XML instead of HTML, since you can now have your own custom schema.

Also don't use YAML, as that's far more unreliable. (If you chop a YAML file in half, it's still valid)

It ended up being a large document but it was infinitely more useful than plain old markdown. I think I’ll do it more often now. Creating interactive specs is a really fascinating way to work. I’ve always verified my work in similar ways, but this was more… Verification-forward, I guess. And it took hours instead of days.

It’s actually really fun to be building and refactoring these days. No idea how long the fun will last, but I’m thoroughly enjoying it right now. I know it will make some people think I’m a hack, but I know that approach enabled me to do a faster, more targeted, ultimately better job of improving state management in the application. It’s not because Claude wrote the code (I still did quite a bit of it), but because Claude helped me establish the right work to do for the right reasons, using tools I couldn’t dream of throwing together 5 years ago.

Sure enough, this is full of listicles and of a length no human would write for an idea as simple as "Use HTML instead of Markdown."

Though now I'm wondering: why not just add full HTML embedding support as well? I'm talking not just for specific deliverables, but for any of the agent's responses with the user.

What happens when my site changes style, I put it back through the LLM I guess and get some bonus hallucinated content.

Classical overly confident llm bullshitting.