Markdown won the first phase of agent documents because it is small, predictable, and easy to diff. But a lot of the documents we actually hand to agents are not small Markdown files. They are PDFs with tables, sidebars, forms, page sections, diagrams, and layouts that carry meaning. Flattening all of that into Markdown is useful. It is not always enough.
Thariq Shihipar made the stronger version of this argument in "Using Claude Code: The Unreasonable Effectiveness of HTML". His point is simple: when agents produce work for humans to review, HTML is often a better medium than Markdown. It can hold more information, show structure visually, support interaction, and open anywhere with a browser.
That argument does not only apply to agent-generated plans and design reviews. It applies to document ingestion too. If HTML is becoming a better way for agents to communicate with us, PDF conversion tools should not stop at Markdown. They should offer HTML when the source document needs its structure preserved.
Markdown is still good. It is just not the whole answer.
For long-running AI workflows, Markdown remains the right default. It is compact. It is easy for models to parse. It works well for headings, paragraphs, lists, links, code blocks, and simple tables. That is why BlazeDocs started with PDF to Markdown and why Markdown will stay the default output for most API and CLI workflows.
The problem appears when the original PDF uses layout as part of the content. A financial statement with nested tables is not just text. A technical manual with warnings, callouts, part numbers, and diagrams is not just text. A policy document with multi-level tables and footnotes is not just text. Markdown can approximate those structures, but the approximation gets thin fast.
The short version
Use Markdown when you want clean semantic text for search, RAG, summarisation, and editing. Use HTML when preserving tables, layout, visual hierarchy, and shareable documentation matters more than having the smallest possible plain-text representation.
Why HTML fits agent work
Thariq's article frames HTML as a richer output format for Claude Code: specs with tabs, visual design directions, annotated pull requests, module maps, dashboards, and small interactive tools. The companion examples show self-contained HTML files replacing the long Markdown document that everyone says they will read and nobody actually reads.
The same properties make HTML useful as an ingestion format for agents:
- Tables keep their shape. HTML tables can preserve row spans, column spans, headers, captions, and nested structure in a way Markdown tables cannot.
- Visual hierarchy survives. Sections, callouts, small print, lists, blocks, links, and code can stay distinct instead of collapsing into one long transcript.
- Humans can review the output. A browser-rendered HTML document is much easier to inspect than a 2,000-line Markdown dump.
- Agents can still read it. Modern models already handle HTML well, especially when the markup is clean, semantic, and stripped of unnecessary chrome.
This is the part that matters for documentation teams: HTML lets the same converted file serve both the agent and the human reviewer. The agent gets structured markup. The human gets a document they can open, scan, and share.
PDF to HTML is the missing option for documentation
A lot of documentation pipelines treat PDF to Markdown as the final step. Convert the PDF, chunk the Markdown, embed it, and move on. That works for many knowledge-base documents. It works less well when the PDF is full of layout-sensitive information.
PDF to HTML gives teams another lane. Instead of asking Markdown to represent every document shape, you can choose the output that fits the job:
Choose Markdown for agent ingestion
Clean text, predictable chunks, smaller payloads, and simpler downstream processing. This is still the right choice for most RAG and summarisation workflows.
Choose HTML for structure and review
Better table fidelity, richer formatting, browser-native sharing, and a more faithful representation of the source document.
The best document tools will support both. Markdown for compact semantic extraction. HTML for fidelity. The mistake is pretending one format should handle every workflow.
Tables are where this becomes obvious
Markdown tables are fine until they are not. They struggle with merged cells, nested headers, footnotes, multi-line cells, and irregular layouts. Those are exactly the tables found in annual reports, compliance manuals, price books, clinical guidance, engineering specs, and procurement documents.
HTML tables are not glamorous, but they are practical. They can preserve the shape of the source table in a way that both people and agents can reason about. If an agent needs to compare values across columns, understand a grouped heading, or quote a row accurately, the structure matters.
curl -X POST https://blazedocs.io/api/v1/convert -H "Authorization: Bearer $BLAZEDOCS_API_KEY" -F "file=@manual.pdf" -F "output_format=html"The response still includes Markdown for compatibility, but the primary content field becomes HTML when requested. That gives you a table-preserving output without breaking existing Markdown-based integrations.
Where this goes next
I do not think Markdown disappears. It is too useful. But the default agent workflow is changing from "give me a text file" to "give me the best artifact for the job." Sometimes that artifact is a Markdown file. Sometimes it is a browser-native HTML document with tables, diagrams, links, and enough visual structure that a person can actually review it.
For PDF conversion, that means the output format should be a choice, not a constraint. If you are building a RAG system, Markdown is probably the starting point. If you are building a documentation pipeline where accuracy, tables, and reviewability matter, PDF to HTML deserves a serious look.
Try both outputs
BlazeDocs now supports Markdown by default and table-preserving HTML when you request it. Start with the API docs, or convert a PDF from the dashboard and compare the outputs on a real document with complex tables.