How do I share an Asciidoctor HTML document?

Publish the rendered `.html` to Comma. If you used asciidoctor-diagram or images, publish the output folder instead so the generated SVGs upload alongside the page and their references are rewritten to the uploaded copies.

How do I make the output a single self-contained file?

Render with `asciidoctor -a data-uri -a allow-uri-read document.adoc`, which inlines images and the stylesheet as data URIs. That produces one portable file — at the cost of size, since every diagram is base64-encoded into the page.

Why do my diagrams disappear when I send the HTML?

asciidoctor-diagram renders PlantUML, Mermaid and Graphviz blocks to image files next to the document and links them relatively. Send just the HTML and those links point at nothing. Publish the folder, or render with `-a data-uri` to inline them.

Can I keep the document in version control and publish on merge?

Yes, and that is the point. Render in CI and PATCH one report id per document, so the URL in the wiki or the ticket always resolves to the current version of a spec that lives in git.

Can reviewers comment on a section of the spec?

Yes. Threads anchor to the rendered content, so a comment on a specific requirement stays on that requirement — which is what makes an AsciiDoc spec reviewable without moving it into a wiki.

Share an AsciiDoc document

AsciiDoc is what people move to when Markdown runs out — admonitions, conditional includes, real cross-references, a proper table model, and diagrams generated from source. It is the format of choice for specs, runbooks and architecture decision records that live in git next to the code they describe.

asciidoctor -a toc=left -a sectanchors spec.adoc     # → spec.html

Living in git is exactly the problem when somebody outside the repo needs to read it. .adoc renders on GitHub, badly and only for people with repo access. The rendered HTML is a file, which means an attachment. So specs get copied into Confluence, and the copy diverges from the source within a month.

The single-file version

asciidoctor -a data-uri -a allow-uri-read \
            -a toc=left -a sectanchors \
            spec.adoc -o spec.html

data-uri inlines the stylesheet and every image as base64, giving you one portable file. Publish it directly — drag it into the app, or:

curl -fsS -X POST "https://commareports.com/api/v1/reports" \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile html spec.html \
        --arg t "Ingest pipeline — design spec v3" '{title: $t, html: $html}')"

When there are diagrams

asciidoctor-diagram is the usual reason the output stops being one file:

[plantuml, ingest-flow, svg]
....
@startuml
Producer -> Queue : publish
Queue -> Worker : consume
@enduml
....

asciidoctor -r asciidoctor-diagram -D out spec.adoc

That writes out/spec.html plus out/ingest-flow.svg and friends, linked relatively. Send the HTML alone and the diagrams are broken images.

Two options:

Publish the folder. Drop out/ into the app: spec.html becomes the report body and the SVGs upload as assets with references rewritten.
Inline them with -a data-uri, keeping one file. Practical for a handful of diagrams; large for a document with twenty.

Publish on merge

The reason to keep a spec in git is that it gets reviewed like code. The reason people abandon that and move it to a wiki is that nobody outside the repo can read it. Rendering in CI closes the gap:

asciidoctor -r asciidoctor-diagram -a data-uri -a toc=left -D out spec.adoc

curl -fsS -X PATCH "https://commareports.com/api/v1/reports/$REPORT_ID" \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile html out/spec.html \
        --arg t "Ingest pipeline — design spec" '{title: $t, html: $html}')"

One report id per document, PATCHed on merge to main. The URL you pasted into the ticket six months ago still resolves to the current spec, the source stays in git under review, and the revision list is the document's history — with the git commits as its provenance. See publishing from CI.

What review adds

Anchored threads on a requirement, so "this conflicts with the retention policy" is attached to the clause it conflicts with. See commenting on HTML.
Revisions, so a reviewer returning after two weeks can see what moved.
Access per report — private, team, domain-gated or named reviewers. A design spec for an unreleased system is not a public document. See the sharing model.

Limits

Entry HTML: 5 MB. -a data-uri with many diagrams is what pushes past it — publish the folder instead when it does.
60 requests/minute per token.

Try it

Comma is free — unlimited reports, unlimited commenters, unlimited revision history.

Publish a document →