Show HN: Neither HTML nor Markdown is enough: a way out of the AI doc dilemma
GEML is a plain-text document format that combines human-readable Markdown-like syntax with agent-addressable, ID-tagged blocks for precise read/write operations It solves the "read-to-write ratio" problem where AI agents must read entire documents to make small edits, demonstrated by a 20:1 read-to-write ratio in a Claude Code workflow Benchmarks across 47 real edits showed GEML reduces addressing costs by 21x and bytes read by 3.1x compared to Markdown The format supports bound charts (data bo
Analysis
TL;DR
- GEML is a plain-text document format that combines human-readable Markdown-like syntax with agent-addressable, ID-tagged blocks for precise read/write operations
- It solves the "read-to-write ratio" problem where AI agents must read entire documents to make small edits, demonstrated by a 20:1 read-to-write ratio in a Claude Code workflow
- Benchmarks across 47 real edits showed GEML reduces addressing costs by 21x and bytes read by 3.1x compared to Markdown
- The format supports bound charts (data bound by ID to prevent drift), strict reference validation via
geml check, and block-level version history through.gemlhistorysidecars - GEML is designed as a stable 1.0 spec with MIT code and CC-BY documentation, offering bidirectional conversion to/from GitHub-Flavored Markdown without locking users in
Why It Matters
This addresses a fundamental bottleneck in AI-assisted document editing: as context windows grow, the limiting factor shifts from token capacity to the inefficiency of flat-text addressing. For AI practitioners building agent workflows around documentation, GEML offers a practical middle ground between HTML's addressing capabilities and Markdown's human readability, potentially reducing token costs and improving edit accuracy in agent-driven pipelines.
Technical Details
- Block-addressable architecture: Every block carries a stable
#id, enablinggeml getto retrieve individual blocks andgeml setto swap them without reading entire files, with integrity checks that refuse writes breaking document structure - Dual rendering pipeline:
--to htmlproduces rich human-readable output;--to mdprojects back to GitHub-Flavored Markdown, with dropped features (block IDs, bound charts) explicitly named rather than silently lost - Validation and integrity:
geml checkacts as a compiler-style build step, producing non-zero exit codes for dangling or cross-document references; bound charts tie visualizations directly to source tables by ID - Versioning:
geml historymaintains micro-revisions in a plain-text.gemlhistorysidecar file, enabling block-level rollback without polluting git commit logs - Parser conformance: The spec includes a conformance suite validated by an independent parser written from the spec alone, ensuring cross-implementation consistency unlike ad-hoc Markdown extensions
Industry Insight
- The 20:1 read-to-write ratio observed in real agent workflows suggests that document format choice is a significant cost factor in AI agent operations; adopting addressable formats could yield substantial token savings at scale
- GEML's approach of treating HTML as generated output and maintaining a plain-text source reflects a growing pattern where AI agents need structured, machine-addressable documents rather than flat text — this could influence tooling design for agent-document interactions
- The explicit rejection of Markdown extensions in favor of a unified spec with a build step mirrors lessons from the web's fragmentation era; expect similar pressure for standardized document models in AI-native workflows, particularly where cross-document references and data binding matter
Disclaimer: The above content is generated by AI and is for reference only.