Why is my Dokka HTML output broken when I open index.html directly?

Because the page fetches its navigation and search index as separate resources, and browsers block those requests from `file://` origins. The nav pane comes up empty and search returns nothing. It needs to be served over HTTP — publishing it is the shortest way to do that.

How do I share Dokka docs?

Run `./gradlew dokkaHtml` (or `dokkaGenerate` on Dokka 2), then drag `build/dokka/html/` into Comma. `index.html` becomes the report body and the navigation, scripts, styles and package pages upload as assets with their references rewritten.

Does search work at the published URL?

Yes — the search index uploads with the rest of the site and its reference is rewritten to the uploaded copy, so the requests that failed at `file://` succeed over HTTP.

Can I publish a multi-module project's docs?

Yes. `dokkaHtmlMultiModule` produces a single site with a module index; publish that folder. If it exceeds the 500-asset cap, publish per module with one report id each.

Can reviewers comment on a class's docs?

Yes. Anchored threads attach to the rendered page, so a note about an undocumented nullable return lands on the function instead of in a ticket.

Share Dokka HTML docs

Dokka's HTML output is the nicest-looking API reference in the JVM world, and it has a specific failure that catches everyone once: double-clicking index.html gives you a page with an empty navigation pane and a search box that finds nothing.

That is not a broken build. The site loads its navigation and search index as separate resources, and browsers refuse those requests from a file:// origin. Dokka's output needs to be served over HTTP.

Generate

Dokka 2:

./gradlew dokkaGenerate         # → build/dokka/html/

Dokka 1:

./gradlew dokkaHtml             # → build/dokka/html/
./gradlew dokkaHtmlMultiModule  # multi-module: one site with a module index

Publish the folder

Drag build/dokka/html/ (or a zip of it) into the app:

index.html becomes the report body.
navigation.html, the search index, scripts/, styles/, images/ and every package and class page upload as assets, and their references are rewritten to the uploaded copies.
Scripts run inside a sandboxed iframe (allow-scripts, no allow-same-origin), so the nav tree expands and search returns results.

The requests that fail at file:// succeed over HTTP. That is the entire fix, and it is also why "just zip it and send it" never works for Dokka.

From CI

./gradlew dokkaGenerate

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 build/dokka/html/index.html \
        --arg title "API docs — $VERSION" '{title: $title, html: $html}')"

PATCH one report id per library and the link stays valid across releases, with each release kept as a revision. See the API docs for the asset endpoint.

What review adds

Anchored threads on a class or function — missing @throws, a stale sample, a nullable return nobody documented. See commenting on HTML.
Access per report — private while the API is unstable, public at release. See the sharing model.

Limits

Entry HTML: 5 MB. Assets: 25 MB per file, 250 MB and 500 files total. A large multi-module project is the case that approaches the file cap — publish per module if it does.
60 requests/minute per token.

Try it

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

Publish generated docs →