> For the complete documentation index, see [llms.txt](/llms.txt)

# The generated docs site

Alongside the SDKs, Glotto emits a complete **Astro + React + Tailwind docs project your
customer owns** — generated from the same [Glotto IR](/docs/glotto-ir) and the per-language
SDK snippets, so the docs never drift from the SDKs.

> This is the *generated customer* docs site (the `@glotto/codegen-docs` output). It is a
> different surface from this site — Glotto's own docs, which you're reading now.

## What it includes

- **Reference pages** — one per operation, with params and request/response schema.
- **Multi-language snippet tabs** — populated from the emitted SDK snippets.
- **MDX / Markdown / Markdoc authoring** for narrative pages — guides live in a typed,
  schema-validated collection (`src/guides/`), so a new file is routed, listed, and indexed
  automatically.
- **Search** (Pagefind), opened with Cmd-K / Ctrl+K and navigable with the arrow keys, with facets
  by HTTP method, resource, SDK language, and parameter name. Facet labels and order are
  configurable through `docs.search.facets`, alongside a **CSS-variable theming** system.
- **First-party, cookieless analytics** (opt-in, off by default) against your own PostHog or
  Plausible project — page views plus search-query, feedback-vote, and playground events, with
  Do-Not-Track honored and no cookies or consent banner.
- **Branch-preview deploys** and **custom-domain + SSL** wiring.
- **Third-party decorators** — inject snippets into the OpenAPI doc as `x-codeSamples` for
  customers who host docs on Mintlify / ReadMe / Redocly / Bump / GitBook.
- **An MCP connect page** — when your `glotto.yml` has an `mcp` block, a nav-linked
  `/connect-mcp/` page carries the install blocks (`claude mcp add`, `.mcp.json`, a Cursor
  install link) for your [generated MCP server](/docs/mcp-server).

## Hosting your docs elsewhere: the decorated spec URL

If you host your reference docs on **Mintlify, ReadMe, Redocly, Bump or GitBook** rather than
on the generated site, Glotto publishes the decorated OpenAPI document — your spec with the
per-language SDK snippets injected as `x-codeSamples` (or `x-code-samples` for ReadMe) — at a
stable URL your provider can point at:

```
https://api.glotto.dev/v1/spec/decorated/<projectId>/openapi.decorated.yml
https://api.glotto.dev/v1/spec/decorated/<projectId>/openapi.decorated.json
```

Paste it into `mint.json` (or your provider's spec-URL field) **once**. The address never
changes and is not tied to a spec revision: it always serves the most recent decorated
document, so every regeneration reaches your docs provider with no CI step of your own.

Pick the format by **extension** — the URL determines whether you get YAML or JSON, so the
same link always means the same thing. Responses carry a strong `ETag`, so a provider that
polls gets a cheap `304 Not Modified` until the document actually changes.

This is **opt-in per project and off by default**: until you enable it, the URL returns `404`,
and a project that has not opted in is indistinguishable from one that does not exist. Turn it
on in your project config:

```yaml
hosted_spec:
  enabled: true
```

The document is served without authentication — that is what lets a docs provider fetch it —
so enable it only for a spec you are comfortable publishing.

The source-of-truth template lives in `templates/docs-site-template/`; the customer can
override any Astro/React component.