Why does a DocFX site not work from the filesystem?

The generated site loads its table of contents and search index over XHR, and `file://` origins block those requests. `docfx serve` exists precisely because the output expects a server.

The whole `_site/` folder. `index.html` is the entry; the `toc.json`, the search index and the styles have to travel with it or the navigation is empty.

Does the API search box still work?

Yes. Report HTML renders with scripts enabled inside a sandboxed iframe and the index files upload as assets with their references rewritten, so search and the namespace tree behave.

Can I do this per pull request?

Yes — one report id per branch, PATCHed on each build. That gives reviewers a working API reference for the change without provisioning anything.

Should this replace our published docs site?

No. It replaces the preview environment — the temporary host you would otherwise stand up so somebody can read the docs before they merge.

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

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

Publish the folder

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

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:

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

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 →