# Share YARD Docs — Ruby API Documentation at a Link

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

> yard doc writes a doc/ folder that needs a server to browse properly. Publish it to Comma for a URL where the index, search and frames all resolve.

# Share YARD docs

`yard doc` gives Ruby projects a genuinely good API reference: a class list, a
method index, the source of every method one click away, and full-text search.
It also gives you `yard server`, which exists mostly because the generated
site does not behave when opened as a `file://` path — the frame navigation
and search load sibling files that the browser blocks at that origin.

So the docs work on your machine, with a server running, and nowhere else.

## Generate

```bash
gem install yard
yard doc          # → doc/
```

Include the private API too if the audience is your own team:

```bash
yard doc --no-private --protected
```

## Publish the folder

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

- `index.html` becomes the **report body**.
- The class and method pages, `js/`, `css/`, `_index.html` and the search data
  upload as assets, and their relative references are rewritten to the
  uploaded copies — which is precisely the step `file://` refuses to do.
- Scripts run inside a sandboxed iframe (`allow-scripts`, no
  `allow-same-origin`), so search and the source toggles work.

One URL. No `yard server` on somebody's laptop, no `doc/` committed to git.

## From a release workflow

```bash
yard doc

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

PATCH one report id per gem: a stable link for the README, a revision per
release. See the [API docs](/docs/api) for uploading the rest of the folder.

## What review adds

- **Anchored threads** on a method — undocumented raises, stale examples,
  arguments whose meaning changed. See [commenting on HTML](/comment-on-html).
- **Access per report** — private for an unreleased gem, opened up on release.
  See the [sharing model](/docs/sharing).

## Limits

- **Entry HTML: 5 MB.** Assets: 25 MB per file, 250 MB and 500 files total.
  A large gem's per-method pages are the thing that approaches the file cap.
- **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 a RuboCop report](/share-rubocop-report) · [Share an RSpec report](/share-rspec-report)
- [Share a SimpleCov report](/share-simplecov-report) · [Share TypeDoc output](/share-typedoc)
- [Share Javadoc](/share-javadoc) · [Publish from CI](/docs/ci)