# Which Doc Format is Best for AI Specifications?

DevFeed: [Which Doc Format is Best for AI Specifications?](<https://devfeed.tech/articles/which-doc-format-is-best-for-ai-specifications-30762.md>)

Original publisher: [Read original article](<http://blog.vanillajava.blog/2026/07/which-doc-format-is-best-for-ai.html>)

Author: Peter Lawrey (noreply@blogger.com)

Published: 2026-07-14T14:00:28Z

Content type: article

Language: en

Sources: [Vanilla Java](<https://devfeed.tech/sources/vanilla-java.md>)

Topics: [Specifications](<https://devfeed.tech/topics/specifications.md>), [Markdown](<https://devfeed.tech/topics/markdown.md>), [Fable](<https://devfeed.tech/topics/fable.md>), [HTML](<https://devfeed.tech/topics/html.md>), [Documentation](<https://devfeed.tech/topics/documentation.md>)

Tags: [ai](<https://devfeed.tech/tags/ai.md>), [fable](<https://devfeed.tech/tags/fable.md>), [html](<https://devfeed.tech/tags/html.md>), [info](<https://devfeed.tech/tags/info.md>), [markdown](<https://devfeed.tech/tags/markdown.md>), [readability](<https://devfeed.tech/tags/readability.md>), [specifications](<https://devfeed.tech/tags/specifications.md>)

## AI overview

The article compares Markdown, AsciiDoc, and HTML for AI specifications using document-size, markup-overhead, readability, and editing-workflow observations. It recommends Markdown for AI working documents, AsciiDoc for curated human-reviewed specifications, and HTML primarily as a publishing target.

## Source excerpt

I have a Spec Driven Project with 674 documents incl 181 specs, 429 tasks, and 40 project docs. About 1/3 of these are an acceptance sub-project to show the root project meets fit-for-purpose requirements. I used Fable to convert these to and from AsciiDoc, Markdown, and HTML. From this, I tried to draw some conclusions about which format is better than the others for AI specifications. TL;DR: Markdown for AI working documents, AsciiDoc for curated human-reviewed specs, HTML only as a publishing target. Objective Metrics Corpus Tokens (Approx) Markdown: 594k, AsciiDoc: 598K, HTML: 661k Worst Single-File Ratio AsciiDoc: 1.023x, HTML: 1.26x (due to tables and code blocks) Markup share of file content Markdown 0.9%, AsciiDoc 1.3%, HTML 9.9% - a 10x overhead for HTML Read/write Assessment In terms of readability, both Markdown and AsciiDoc are good. HTML has far more tags, which add noise. One of the most common tags is <code>some code</code> however in the other formats, this is just `some code` When you have an average of 16 per file, this adds a lot of noise. Usability GitHub renders both Markdown and AsciiDoc with working links and checkboxes; HTML is shown as raw source, so the review loop dies there. The first two are also easier to view while you're editing in IntelliJ. HTML is more difficult to read and edit, and it is not as easy to view the rendered output. If you occasionally need HTML, you don't need HTML files: embed an island with ```{=html} in Markdown (Pandoc raw-attribute syntax) or in AsciiDoc. It renders where HTML is supported and drops out cleanly elsewhere. If you really need to use HTML, you can include a link to a file in that format. Note As these were one-for-one conversions, I didn't use features that only exist in AsciiDoc or HTML, such as. Markdown vs AsciiDoc While you might choose either format for your specs, I have been following this convention to keep the authoring consistent. Markdown used for AI-generated content, not human-written,