Markdown is for Thinking. HTML is for Showing.

2026-05-18 · Source: Towards AI - Medium · Field: Technology & Digital — Artificial Intelligence & Machine Learning, Software Development & Engineering · Depth: Intermediate, quick

Summary

The article addresses why AI-generated technical specifications, often presented in markdown, are frequently unread, proposing a two-stage workflow to improve their utility. It draws an analogy between architectural sketches and blueprints to distinguish between early-stage, messy ideation and polished, final documentation. The author recounts an experience where a 340-line markdown file from Claude for a database migration was overwhelming and unhelpful. This observation is framed against a debate between Thariq (Anthropic), who advocates for HTML for AI code output due to its density and shareability, and Daniel Miessler (PAI Founder), who argues for text's direct connection to thought. The article suggests both perspectives are valid but incomplete, implying a need for a structured approach to AI output presentation.

Key takeaway

For AI Architects and Engineers generating technical specifications, recognize that raw AI output in markdown often serves as a "pencil sketch" for ideation, not a final "blueprint." You should implement a two-stage process: use markdown for initial AI-assisted brainstorming, then refine and present critical information in a more structured, readable format like HTML for stakeholder review and implementation, ensuring clarity and actionability.

Key insights

AI output needs a two-stage workflow, distinguishing between raw ideation and polished presentation.

Principles

• Match tool to job
• Clarity over density
• Separate ideation from presentation

In practice

• Use markdown for early-stage AI ideation
• Convert polished AI output to HTML for sharing

Topics

• AI Content Generation
• Markdown Formatting
• HTML Presentation
• Technical Documentation
• Information Readability

Best for: AI Engineer, AI Architect, Director of AI/ML

Related on AIssential

• TEST: Text to Image AI Generator for Technical Stuff — AI image generators vary significantly in their ability to render complex technical infographs from identical text prompts.
• 🎙️ How I AI: HTML is the new Markdown: How Anthropic engineers are building with Claude Code — HTML offers richer, more interactive communication with AI agents than Markdown, enhancing engagement and product quality.
• A picture is worth a thousand words for an LLM — Mood boards and style references are crucial for guiding AI image generation towards a specific aesthetic.
• Build your own AI tools to fill specific workflow gaps — Custom AI tools can bridge workflow gaps by enabling AI models to interpret and generate structured visual designs.
• Why Most AI Art Prompts Fail. And How to Write Better Ones — AI art generation is a linguistic process where precise prompts are crucial for consistent, intentional image outcomes.
• Using Claude Code: The Unreasonable Effectiveness of HTML — HTML offers richer, more interactive LLM outputs than Markdown, improving clarity and navigation for complex information.

Open in AIssential →

Editorial summary, takeaway, and curation by AIssential. Original article published by Towards AI - Medium.