How do I share generated JSDoc output?

Run `npx jsdoc -c jsdoc.json -d docs/`, then drag the whole `docs/` folder into Comma. `index.html` becomes the report body and every symbol page, stylesheet and script uploads alongside it with its references rewritten.

Why not just commit docs/ to the repo?

Because generated output in version control produces a diff on every commit that nobody reviews, and readers still have to clone the repo to open it. A published link is one URL, updated in place by CI.

Does the sidebar navigation work?

Yes. The default template links between pages with relative hrefs, and those references are rewritten to the uploaded assets on publish, so class and module pages resolve the same way they do locally.

Can I publish docs for a pre-release branch?

Use a separate report id per branch or version. Each gets its own URL, so a release candidate's docs never overwrite the ones people are reading.

Can reviewers comment on a doc page?

Yes. Anchored threads sit on the rendered symbol, so "this param description is wrong since v4" lands on the method rather than in an issue that paraphrases it.

Share JSDoc output

jsdoc -d docs/ produces a small static site: index.html, a page per module and class, styles/, scripts/, and a nav built from your @module tags. Then you have to decide where it lives, and the usual options are all bad — commit it and every build dirties the diff, or push it to a docs host and maintain another deployment.

Generate

npm i -D jsdoc
npx jsdoc -c jsdoc.json -d docs/

A minimal jsdoc.json:

{
  "source": { "include": ["src"], "includePattern": ".+\\.js$" },
  "opts": { "recurse": true, "destination": "docs/" }
}

Publish the folder

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

index.html becomes the report body.
Every symbol page, styles/jsdoc.css, scripts/ and the fonts upload as assets, and their relative references are rewritten to the uploaded copies.
Scripts run inside a sandboxed iframe (allow-scripts, no allow-same-origin), so the collapsible nav and the source-view links work.

One URL for the API surface — no docs/ in git, no static host to keep alive.

From CI

npx jsdoc -c jsdoc.json -d 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 title "API docs — v$npm_package_version" \
        '{title: $title, html: $html}')"

PATCH the same report id on release and the link in your README always points at current docs, with every previous version kept as a revision. See the API docs for uploading the rest of the folder as assets.

Use a separate report id per major version if you support more than one — distinct URLs, no overwriting the docs people are actively reading.

What review adds

Anchored threads on a symbol — "this @returns is stale". See commenting on HTML.
Access per report — private while a feature is unreleased, public when it ships. See the sharing model.

Limits

Entry HTML: 5 MB. Assets: 25 MB per file, 250 MB and 500 files total. A large API surface can approach the 500-file cap — publish per package if it does.
60 requests/minute per token.

Try it

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

Publish generated docs →