How do I share DocC documentation with someone who doesn't use Xcode?

Build with `--transform-for-static-hosting`, which turns the archive into a plain folder of HTML and JSON, then publish that folder to Comma. The reader opens a URL in any browser — no Xcode, no archive to double-click.

Why can't I just send the .doccarchive?

A `.doccarchive` is a bundle Xcode's documentation viewer opens. Sent to someone without Xcode it is an opaque folder, and unzipped on a filesystem its `index.html` renders empty because the renderer fetches its JSON over XHR, which a `file://` origin blocks.

Do deep links into /documentation/... work?

The entry page and in-page navigation work, because the renderer is a client-side app that routes internally. Pasting a deep path directly as a URL relies on server-side rewrites, so link people to the report URL and let them navigate — or publish the specific symbol page as its own report.

Can I publish docs for an unreleased SDK privately?

Yes. Access is set per report — private, your team, anyone signed in at your domain, or anyone with the link. A partner SDK under NDA gets a link-only URL without going on the open web.

Can the docs job keep one permanent link?

Save the report id and PATCH it on every release. The URL stays constant and each publish appends a revision, which doubles as a record of how the public API changed.

Share a DocC archive

DocC produces genuinely good documentation — symbol pages, tutorials, articles, all generated from the source of truth. Then it hands you a .doccarchive, which is an Xcode artifact, and the handoff falls apart the moment the reader is a backend engineer, a partner, or anyone on a machine without Xcode installed.

Zipping it does not help. Unzipped, index.html opens to a blank page: the DocC renderer is a JavaScript app that fetches its content as JSON, and a browser blocks that fetch from a file:// origin. The docs are all there. The page just never asks for them successfully.

Build the static-hosting output

One flag changes the shape of the output from "Xcode bundle" to "folder of files a browser can serve":

swift package --allow-writing-to-directory ./docs \
  generate-documentation --target MyKit \
  --transform-for-static-hosting \
  --output-path ./docs

For an Xcode project:

xcodebuild docbuild -scheme MyKit -derivedDataPath ./dd
xcrun docc process-archive transform-for-static-hosting \
  ./dd/Build/Products/Debug-iphoneos/MyKit.doccarchive \
  --output-path ./docs

docs/
├── index.html
├── documentation/   # per-symbol pages
├── data/            # the JSON the renderer fetches
├── css/  js/  images/
└── metadata.json

Drop the folder in

Drag docs/ (or a zip of it) into Comma:

index.html becomes the report body.
data/, js/, css/ and every symbol page upload alongside it, with relative references rewritten to the uploaded copies — which is the step that fixes the blank page, because the JSON now resolves over https://.
Scripts run inside a sandboxed iframe (allow-scripts, no allow-same-origin), so the renderer boots, the sidebar tree works, and in-page search runs.

No bucket, no Pages workflow, no server-side rewrite rules to get right.

From the release job

swift package --allow-writing-to-directory ./docs \
  generate-documentation --target MyKit --transform-for-static-hosting --output-path ./docs

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

Supporting files go up through POST /api/v1/reports/$REPORT_ID/assets as base64 — one call per file, worth scripting once. See the API reference and publishing from CI.

Doc review that lands on the symbol

"This doesn't say whether it can throw" is worth something attached to the initializer and nothing at all in a channel. Threads anchor to the rendered content and survive rebuilds, so the list of places where the types are self-explanatory and the behaviour is not stays attached to the docs. See commenting on HTML.

Limits

Entry HTML: 5 MB. Assets: 25 MB per file, 250 MB and 500 files total. A large framework's data/ tree can exceed 500 files — narrow to the public target, or publish one module per report.
Scripts run, sandboxed — no same-origin access.
60 requests/minute per token.

Try it

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

Publish DocC output →