Comma

Share TypeDoc output

TypeDoc reads your types and writes a documentation site. The documentation site is the problem: docs/ is a folder of a few hundred files that needs somewhere to live before it is documentation and not just output.

For a public package, GitHub Pages settles it. For an internal library, a partner SDK, or a branch you want someone to review before it ships, the hosting question is out of proportion to the need.

Build it

npx typedoc --out docs src/index.ts

docs/
├── index.html
├── modules.html
├── classes/  interfaces/  functions/
└── assets/          # css, js, and the search index

Publish index.html on its own and you get an unstyled page with dead links and no search. It's a folder.

Drop the folder in

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

  • index.html becomes the report body — the page carrying the comment layer.
  • Every module, class and interface page plus assets/ uploads alongside it, and relative href references are rewritten to the uploaded copies.
  • Scripts run inside a sandboxed iframe (allow-scripts, no allow-same-origin), so the search box and the theme toggle keep working — search being most of what makes generated API docs usable.

One URL, no bucket, no DNS, no Pages workflow.

From the release job

npx typedoc --out docs src/index.ts

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 title "API — v$npm_package_version" \
        '{title: $title, html: $html}')"

The API is JSON-only, so the supporting pages 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.

PATCHing one saved id keeps a permanent URL whose content tracks the current release, with a revision per publish. That history is the honest answer to "when did this signature change?"

Docs review, on the docs

Documentation feedback is specific and normally lost. "This doesn't say whether the callback can throw" is worth a lot attached to the function and nothing at all in a channel.

Select the description, leave a thread, and it stays anchored to that symbol across docs builds — a standing list of exactly where the types are self-explanatory and the behaviour isn't. See commenting on HTML.

Who can see it

Per report: private, your team, anyone signed in at your domain, or anyone with the link, with view / comment / edit rights for link holders. See sharing & access control.

Limits

  • Entry HTML: 5 MB. Assets: 25 MB per file, 250 MB and 500 files total. A large surface can exceed 500 pages — narrow the entry points, or use --excludeInternal and --excludePrivate, which usually improves the docs anyway.
  • 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 TypeDoc output →

Related