# Share an AsciiDoc / Asciidoctor HTML Document

Canonical: https://commareports.com/share-asciidoc-html
Published: 2026-09-08

> Asciidoctor renders one HTML file — until diagrams and includes turn it into a folder. Publish it to Comma for a URL with the TOC, the diagrams and a comment thread.

# 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.

```bash
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

```bash
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](https://commareports.com/), or:

```bash
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:

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

```bash
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:

1. **Publish the folder.** Drop `out/` into the app: `spec.html` becomes the
   report body and the SVGs upload as assets with references rewritten.
2. **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:

```bash
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](/docs/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](/comment-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](/docs/sharing).

## 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 →](https://commareports.com/)**

### Related

- [Share a Pandoc HTML file](/share-pandoc-html) · [Share an Antora docs site](/share-antora-docs)
- [Share an mdBook](/share-mdbook) · [Share OpenAPI docs](/share-openapi-docs)
- [Comma vs Confluence](/vs/confluence) · [Embed an HTML report in Confluence](/embed-html-report-in-confluence)