# Share a DocFX Site — .NET API Docs Without an App Service

Canonical: https://commareports.com/share-docfx-site
Published: 2026-09-15

> docfx build writes _site, which needs a server to browse. Publish the folder to Comma for a .NET API reference preview with anchored comments and no hosting.

# Share a DocFX site

DocFX turns XML doc comments and conceptual markdown into a real API
reference — namespace tree, member tables, cross-links into the BCL. It writes
that into `_site/`, and `_site/` is a website, which is to say it needs a
server.

`docfx serve _site` covers the author. It does not cover the reviewer, the
consumer of the library, or the architect who wanted to check one signature.

## Build it

```bash
dotnet tool install -g docfx
docfx docfx.json
# → _site/
```

## Publish the folder

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

- `index.html` becomes the **report body**.
- `toc.json`, the search index, the styles and every generated API page upload
  as assets, with references rewritten to the uploaded copies.
- Scripts run inside a sandboxed iframe (`allow-scripts`, no
  `allow-same-origin`), so the namespace tree and the search box work.

From CI, per branch:

```bash
docfx docfx.json

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

## API review wants the rendered page

A change to a public signature is easy to approve in a diff and hard to
evaluate there — what matters is what the reference will say, which
overloads now collide in the member table, and whether the summary reads as
instructions or as a restatement of the method name.

- **Anchored threads** on the member in question. See
  [commenting on HTML](/comment-on-html).
- **Revisions**, so the before-and-after of a signature change is one click
  apart.
- **Access per report** — private, team, domain-gated, or named reviewers,
  for libraries that are not public yet. 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 generates a page per type and will approach the 500-file
  cap — publish the namespace under review rather than the whole reference.
- **60 requests/minute per token.**

## Try it

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

**[Publish a docs preview →](https://commareports.com/)**

### Related

- [Share a .NET coverage report](/share-dotnet-coverage-report) · [Share an NUnit report](/share-nunit-report)
- [Share Javadoc](/share-javadoc) · [Share TypeDoc](/share-typedoc)
- [Share an HTML folder](/share-html-folder) · [Publish from CI](/docs/ci)