# Share JSDoc Output — Host the docs/ Folder Without a Server

Canonical: https://commareports.com/share-jsdoc
Published: 2026-08-31

> jsdoc -d docs/ writes a multi-page site with its own CSS and scripts. Publish the folder to Comma for a URL where the nav and search still work.

# 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

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

A minimal `jsdoc.json`:

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

## Publish the folder

Drag `docs/` (or a zip of it) into [the app](https://commareports.com/):

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

```bash
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](/docs/api) 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](/comment-on-html).
- **Access per report** — private while a feature is unreleased, public when
  it ships. See the [sharing model](/docs/sharing).

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

### Related

- [Share TypeDoc output](/share-typedoc) · [Share Javadoc](/share-javadoc)
- [Share rustdoc](/share-rustdoc) · [Share Doxygen docs](/share-doxygen-docs)
- [Share OpenAPI docs](/share-openapi-docs) · [Publish from CI](/docs/ci)