Docs Writing

---
title: HTTP/3
description: …
category: transport
crate: tako-rs-server
runtime: tokio
features: [http3]
since: 2.0.0
status: stable
---

# HTTP/3

<one-paragraph what + when. State runtime support up front.>

## Serving it

```rust
// minimal serve example, real API names from tako-rs-server

Use a `<Tabs items={['Tokio','Compio']}>` split only when the transport
ships on both runtimes with different entry points.

### 3.2 Extractor — base: `extractors/body.mdx`

Group page (body / request-meta / auth / cookies). One `##` section per
extractor: the real type name, what it pulls from the request, a handler
snippet, and the feature gate. Put a `<Callout type="warn">` on any
security-sensitive extractor (e.g. unverified JWT claims). Cross-link the
matching middleware (`/docs/middleware/auth`).

### 3.3 Middleware — base: `middleware/auth.mdx`

Group page (auth / security / traffic / metrics). Lead with the
middleware model (`.into_middleware()` vs `router.plugin(...)`), then one
`##` per middleware: constructor, what it does, ordering notes. Verify the
real type names against `tako-rs-plugins` — they differ from the README's
friendly names (`Csrf` not `CsrfMiddleware`, `CookieSigned` not
`SignedCookieJar`).

### 3.4 Plugin — base: `plugins.mdx`

Explain the `TakoPlugin` trait, the `plugins` feature, and the
plugin-vs-middleware split (a plugin can `install()` its own routes;
middleware only wraps the chain). Link to the four middleware group pages.

### 3.5 Concept — base: `concepts/architecture.mdx`

Cross-cutting explanation (architecture, request lifecycle, runtimes,
design philosophy). Prose + tables over code. No per-API depth — link out
to the catalog pages for that.

### 3.6 Tutorial — base: `tutorials/rest-api.mdx`

End-to-end, runnable. Prefer `<RustExample path="examples/…/src/main.rs" />`
over hand-written code. Walk the reader from empty `main` to a working
service; link each building block to its reference page.

### 3.7 Guide — base: `routing.mdx`

Flat top-level page for a request-handling topic (routing, state, streams,
queue, signals, observability, deployment). Task-oriented prose with
focused snippets.

### 3.8 Reference — base: `reference/features.mdx`

Normative: the cargo feature graph, migration ledger,
API index. Tables + exact, exhaustive content. The feature page must cover
every flag in the README "Feature Flags" table.

## 4. meta.json sidebar wiring

- **Top-level** `content/docs/meta.json` orders the whole sidebar and uses
  `"---Section title---"` string entries as group separators (e.g.
  `"---Transports---"`). Folder names (`transports`, `concepts`, …) and
  flat slugs (`routing`, `state`, …) are listed in display order.
- **Folder** `<section>/meta.json` is `{ "title": "...", "pages": [...] }`.
  List `index` first when the folder has an overview page.
- The audit **fails** if an `.mdx` file is not listed in its folder's
  `pages` array. Every new page must be added to the relevant `meta.json`.

## 5. MDX components

Registered globally in `website/mdx-components.tsx` — no import in MDX.

- **`Tabs` / `Tab`** — only for a genuine multi-variant split; the
  canonical tako case is Tokio vs Compio. A lone snippet is a plain
  fenced ```rust block, not a one-tab `Tabs`.
- **`Callout`** — `<Callout type="warn">…</Callout>` (`info | warn |
  error`). Use `warn`/`error` for security gotchas and tokio-only
  constraints.
- **`RustExample`** — `<RustExample path="examples/auth/src/main.rs" />`
  inlines a real workspace file verbatim. The path is relative to the
  **repo root** (`/Users/danixx/Desktop/tako`), not `website/`. The file
  must exist or the audit fails.

Internal links are **site paths**, never `.md`: top-level `foo.mdx` →
`/docs/foo`; `transports/http.mdx` → `/docs/transports/http`; folder index
`transports/index.mdx` → `/docs/transports`.

## 6. Examples must be real

Accuracy is the whole job. Read the crate source before writing — do not
invent signatures or type names. Prefer `<RustExample>` pointing at a real
file in `examples/` over a hand-written snippet. Keep tokio-only vs compio
support correct (the README transport matrix is the reference: HTTP/2 +
TLS, h2c, HTTP/3, WebTransport, raw TCP/UDP, Unix sockets, and PROXY protocol on both runtimes; only the raw QUIC helper `RawQuicSession` is tokio-only). When a
type's friendly name in the README differs from its exported name, document
the exported name and mention the catalog name once.

## 7. The audit-script contract

Run before every commit that touches docs:

```bash
cd website
bun run typecheck    # tsc --noEmit
bun run lint:mdx     # frontmatter zod schema (scripts/lint-mdx.ts)
bun run audit        # lint:mdx + meta coverage + RustExample + link graph
bun run build        # next build — MDX + zod schema, the source of truth