Best Document Format for AI Specifications: Markdown vs AsciiDoc vs HTML

Written by Peter Lawrey, CEO of Chronicle Software.

In this blog I discuss using at first metrics to see what difference using different formats might make, and also considering usability and make the ownership and authority clearer. 

We use AI mostly for research and exploratory work for possible new functionality. Currently this is being used to consider how tooling of Chronicle Queue Enterprise can be extended by prototyping new ideas to see what would be valuable additions.

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 5.0 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

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.

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, often not even reviewed. These are working disposable documents for the AI.

AsciiDoc

used for human-written content, reviewed and approved. These are curated specifications important enough to be preserved and maintained. They are the source of truth for the project.

HTML and DOCX

used for publishing, not for authoring.

In this workflow, AsciiDoc identifies material that humans have taken responsibility for. Markdown is used for exploration and advisory working material. The extension makes that distinction visible; it does not create approval or prove correctness.

Making the distinction clear

Markdown vs Asciidoc alone might not be enough and you could record other details in a front matter block. This might be either visible when rendered or treated as meta data. I favour making it renderable e.g.

```yaml

status: candidate

authority: advisory

owner: <person responsible>

lastReviewed: <date last reviewed, or not reviewed>

reviewTriggers: <a canonical principle change, a public contribution, a material evidence or capability change, or a reported contradiction>

```

These distinctions have been used in the https://github.com/OpenHFT/Open-Understanding project.

Conclusion

The format that works best is not just the one with the fewest tokens. It is the one that humans can review, tools can diff, and AI can consume without wasting context on markup noise.

Markdown and AsciiDoc are close enough in token cost that the more important decisions are how you express requirements, establish authority, and keep evidence attached to the claims.

For this project, Markdown for disposable AI working documents, AsciiDoc for curated human-reviewed specifications, HTML/DOCX for publishing.