Stop Making AI Agents Hand You Markdown Walls

You know that thing where you ask an AI agent for a plan, it gives you 1,800 words of Markdown, and you tell yourself:

"I'll read this properly later."

No, you won't.

You will skim the first section, scroll a bit, get mildly impressed by the bullet points, and then ask the same agent to summarize the summary it just wrote.

I have done this too many times. The agent did the work. The output was technically fine. The Markdown had headings. It had lists. It had just enough structure to pretend it was readable.

But it still felt like homework.

That is the part that started bothering me.

Agents are getting good at doing real work: research, planning, code review, journaling, project updates, decision briefs, and all the other boring-but-useful things that keep a project alive. But after all that work, the default handoff is still usually a wall of Markdown in a chat window.

That feels wrong.

Not because Markdown is bad. Markdown is great. I use it everywhere.

But Markdown is not always the best way to hand work back to a human.

So I built MaraDocs.

The problem is not Markdown

Let me get this out of the way before someone starts defending Markdown like I insulted their family.

Markdown is still excellent for:

• ›notes
• ›source documents
• ›git diffs
• ›grep
• ›long-term memory
• ›agent-to-agent handoff
• ›lightweight documentation
• ›anything that needs to stay boring and portable

I do not want agents to stop using Markdown.

I want agents to stop treating Markdown as the final user interface for every serious deliverable.

There is a difference.

Markdown is a great source format. It is not always a great review surface.

When I ask an agent for a research report, I do not just need text. I need to compare claims, scan sources, see confidence levels, spot risks, and decide what to do next.

When I ask for a project plan, I need timelines, blockers, owners, trade-offs, and next actions.

When I ask for a code review, I need severity, affected files, reproduction steps, and suggested fixes.

Markdown can describe all of that.

HTML can make it usable.

The conversation is already happening

This is not just me being fussy about document formats, although I am absolutely capable of doing that.

In May 2026, Thariq Shihipar from Anthropic's Claude Code team published "Using Claude Code: The unreasonable effectiveness of HTML".

The argument was simple: as agents take on more complex work, humans need better ways to stay in the loop.

A wall of Markdown is often not enough.

Thariq also published a companion gallery with self-contained HTML artifacts for planning, code review, design, prototyping, diagrams, research reports, decks, and custom editors.

That framing clicked for me.

These are not "web pages" in the marketing-site sense. They are work surfaces.

Simon Willison picked up the idea and pointed out that HTML lets agents include navigation, diagrams, SVG, widgets, and richer explanations in a way Markdown cannot.

InfoQ later framed the same shift around human validation in agentic loops. If a human needs to validate agent work, the output should make that validation easier.

The best summary I found came from AgentMail:

HTML wins the session. Markdown wins the archive.

That is almost exactly how I think about it now.

Markdown is for memory.

HTML is for momentum.

Why HTML works better for review

Markdown is linear.

HTML can be spatial.

That difference matters more than it sounds.

A good HTML artifact can give you:

• ›side-by-side comparisons
• ›collapsible sections
• ›source cards
• ›timelines
• ›charts
• ›diagrams
• ›severity labels
• ›sticky summaries
• ›filters
• ›tabs
• ›responsive layouts
• ›shareable links

None of this magically makes the agent smarter.

It makes the human review process better.

That is the part people underestimate. The output format is not decoration. It changes whether the work gets read, trusted, shared, and acted on.

If I am reviewing a long agent-generated research report, I do not want to scroll through an essay. I want a document that helps me make a decision.

That means layout matters.

Hierarchy matters.

Navigation matters.

The handoff matters.

Chat is not a document system

Most agent systems still treat output as text.

The agent thinks. The agent replies. The user reads. Maybe.

But a lot of agent output is not really a reply anymore. It is a work product.

A research brief is a work product.

A weekly operating review is a work product.

A codebase audit is a work product.

A launch plan is a work product.

A personal journal summary is a work product.

A decision memo is a work product.

These things should not be trapped inside a chat bubble.

I wrote about this before in AI Agents Need Artifacts, Not Activity. My rule was simple: serious agent work is not done until it leaves behind a durable artifact.

MaraDocs is the next step in that thinking.

The artifact should not just exist. It should be readable, shareable, versioned, protected when needed, and easy to hand to another human or agent later.

That is where a local report/index.html file is not enough.

Your terminal is not a publishing workflow. A random folder on your machine is not a durable artifact. Chat history is definitely not a filing system, despite humanity's brave attempt to make it one.

So I built the missing handoff layer.

What MaraDocs does

MaraDocs lets agents publish static HTML reports to durable URLs.

Technically, it is a Docker-first static publishing system for agents, CLIs, CI jobs, and scripts.

The basic workflow looks like this:

1. ›An agent creates a static report folder with index.html and assets.
2. ›The agent publishes it with the MaraDocs CLI, REST API, or skill.
3. ›MaraDocs stores the report as a versioned static artifact.
4. ›The agent returns a stable URL to the user.

The smallest version looks like this:

maradocs publish ./report --repo demo --doc hello

That gives you a stable latest URL:

/r/demo/hello/

And an immutable version URL:

/r/demo/hello/v/1/

That distinction is important.

The latest URL is useful for living reports: current project status, current research brief, current dashboard.

The version URL is useful when you need the exact artifact from a specific point in time.

You know, for when future-you asks, "What did the agent actually say before I made that questionable decision?"

Future-you is very judgmental. Give them receipts.

The boring details that make it useful

MaraDocs is intentionally narrow.

It is not trying to be a CMS. It is not trying to be Notion. It is not trying to become yet another dashboard that needs its own dashboard.

It is a report delivery layer for agents.

It includes:

• ›Docker-first server
• ›SQLite metadata
• ›report files stored on disk
• ›CLI publisher
• ›REST API for agents and CI jobs
• ›dashboard for repositories, documents, versions, API keys, and audit history
• ›public, password, and private access modes
• ›stable latest URLs
• ›immutable version URLs
• ›skills.sh-compatible package for agent runtimes

The CLI is published as @maradocs/cli.

The agent skill is published as @maradocs/skill.

The repo is here: github.com/bnap00/maradocs.

The setup is boring on purpose:

cp .env.example .env
# Set COOKIE_SECRET and ADMIN_PASSWORD in .env
docker compose up -d --build

Then install the CLI:

npm install -g @maradocs/cli
maradocs auth login --server http://localhost:8787 --api-key mdo_...

Publish a report:

mkdir -p report
printf '<h1>Hello from MaraDocs</h1>\n' > report/index.html

maradocs repo create demo --access public
maradocs publish ./report --repo demo --doc hello

Now the report is available at:

http://localhost:8787/r/demo/hello/

That is the whole trick.

An agent should be able to do good work and hand back a real artifact, not a scrollback hostage situation.

What this means for OpenClaw

The OpenClaw workflow I want is simple:

Ask for a report, plan, journal, code review, or research brief.

OpenClaw creates a static HTML artifact.

OpenClaw publishes it through MaraDocs.

I get a durable URL instead of a giant chat reply.

The source notes can still go into memory, Markdown, JSON, or whatever the agent needs later.

That gives me two layers:

• ›Source layer: Markdown, JSON, notes, transcripts, memory.
• ›Review layer: HTML artifact with layout, navigation, links, and sharing.

This matters a lot for personal agents.

If an agent is helping with journaling, research, planning, operations, or long-running projects, the output needs to live beyond the chat. It needs a place. It needs structure. It needs to be accessible from other devices and networks.

It needs to become part of the working environment.

Not just a message I vaguely remember receiving.

The safety part matters

HTML is powerful, which is a polite way of saying it can become a mess very quickly.

MaraDocs is static-first. Uploaded files are served as static assets. MaraDocs does not execute uploaded code server-side.

It supports access modes at the repository or document level:

API keys can be scoped for read, publish, or admin.

That matters because handing every agent god-mode credentials is how you turn automation into a haunted toaster.

There is still an important caveat: reports can contain JavaScript because they are static HTML artifacts. For externally shared or untrusted reports, use a dedicated domain or subdomain so report code is isolated from the dashboard origin.

The bigger principle is simple:

Generated HTML should be treated like a published artifact, not a casual chat message.

That means access control, versioning, auditability, and sane defaults.

The future is format negotiation

I do not think the future is Markdown or HTML.

I think the future is format negotiation.

Agents should consume the format that helps them reason. Humans should receive the format that helps them decide.

Sometimes that will be Markdown.

Sometimes JSON.

Sometimes a spreadsheet.

Sometimes a PDF.

And increasingly, for interactive reports and living documents, it will be HTML.

Markdown can be the memory.

HTML can be the room.

MaraDocs is one attempt at building the hallway between them.

Try it

MaraDocs is public now:

• ›GitHub: github.com/bnap00/maradocs
• ›CLI: @maradocs/cli
• ›Skill: @maradocs/skill

It is early, but the core idea is already useful:

Agents should not just finish tasks. They should leave behind artifacts people can actually use.

For quick replies, chat is fine.

For durable knowledge, Markdown is still great.

For human review, sharing, and decision-making, HTML is becoming the obvious surface.

That is why I built MaraDocs.

Not because HTML is new. Obviously it is not. The web is old enough to have knee pain.

But agents are changing what we ask documents to do.

A plan should not just be written. It should be reviewable.

A report should not just be generated. It should be navigable.

A journal should not just be stored. It should be revisitable.

Markdown is for memory.

HTML is for momentum.

MaraDocs is for the handoff.

If you are Gujarati, the project name is exactly what you think it means.

Feel free to connect or reach out if you have questions, or if your agent also keeps handing you Markdown walls and calling it productivity.