Restructure Gateway & Routing, swap OpenRouter for Unsloth, and author docs as .mdx

[SPIKESPIGEL404]

Three things, in three commits: the Gateway & Routing restructure, the model-source swap, and a fix for a rendering bug found while verifying them.

Gateway & Routing

The section is now six pages in reading order, with the separator groups dropped:

1. Model Fallbacks · 2. Provider Selection · 3. Virtual Model · 4. Model Variants · 5. Bring Your Own Model · 6. Bring Your Own Provider

Two renames, for what the thing is rather than what the API field is called. presets.md → virtual-model and byok.md → bring-your-own-provider, both via git mv so history follows. Each page carries a callout noting the wire names are unchanged — the API keeps /v1/namespaces/{nsid}/routing-presets, the routing_preset:* scopes, and byok.

Bring Your Own Model is new. Every technical claim is drawn from existing source-of-truth pages (integrations/models, guides/self-host, ollama/vllm): the api_base/api_protocol/models[].id shape, bitrouter init / config validate, bitrouter route <provider>:<model>, the compatibility.chat_completions switches, and the models: + strategy: priority alias form. It's paired explicitly against Bring Your Own Provider — your weights vs. your account — and hands off to register-as-a-provider for anything Cloud has to reach.

The tools / agents / governance pages (mcp-gateway, server-tools, websearch, web-fetch, acp-gateway, subagent, advisor, fusion, guardrails, structured-outputs) are out of the section nav but stay in the tree at their current URLs, so the ~90 inbound links from other sections keep working. Reverting is one meta.json edit.

Model sources

OpenRouter unpublished. Moved to content/_unpublished/ rather than deleted, dropped from the nav and from the two card grids, redirected to /docs/integrations/models. The aggregator provider block it documented is already the worked example on that page, and /docs/guides/migrate-from-openrouter is untouched.

Unsloth added. There was a stale draft in _unpublished with two real errors, so it was rewritten against Unsloth's current docs rather than published as-is:

• it put the server on :8000; Unsloth defaults to :8888, which also invalidated the reciprocal "vLLM and Unsloth both default to :8000" callout on the vLLM page (removed)
• it carried an import line, which the authoring contract forbids

Verified for the new page: install via curl -fsSL https://unsloth.ai/install.sh | sh; unsloth run --model … prints the endpoint and an sk-unsloth-… key; /v1/chat/completions, /v1/messages, and GET /v1/models all answer on the same port; the key is mandatory, unlike Ollama and vLLM.

.md → .mdx (the reason the last commit touches 45 files)

While verifying the card grids above, it turned out <Callout>, <Cards>, and <Tabs> were rendering to nothing on every docs page — tag and body alike. fumadocs-mdx picks its processor from the file extension and nothing else:

getProcessor(filePath.endsWith(".mdx") ? "mdx" : "md")

format is applied after the mdxOptions spread in the createProcessor call, so no config in source.config.ts can override it. In markdown mode JSX isn't parsed, so <Callout type="info"> opened a CommonMark HTML block running to the next blank line — the whole block became one raw HTML node, and MDX drops those without rehype-raw. That's the bare <!-- --> the pages emitted. This was live on production and affected 41 of 45 pages.

pnpm lint:docs passed throughout, because it validates the component whitelist rather than the output — which is why it went unnoticed.

The fix is the rename alone; no page bodies were edited. The only braces outside code fences are the intended <Tabs items={[…]}> props, there are no bare angle brackets in prose, and the no-imports rule is unaffected since the components are already global via getMDXComponents. check-docs.mjs already matched .mdx?. One hard-coded path in generate-supported-tables.mjs was repointed so prebuild doesn't fail, and the authoring contract in AGENTS.md / docs/CONTRIBUTING.md now says .mdx and explains why the extension is load-bearing.

Checks

• pnpm build — full production build, 120 doc pages prerendered, no MDX parse errors
• pnpm lint:docs — OK, 45 docs across 5 sections
• pnpm test — 83/83
• pnpm generate:cli reproduces the CLI reference byte-identically from the edited overlay
• Recovered content confirmed in the built output; zero escaped <Tabs / <Callout / <Cards remain. Card links on /docs/integrations now appear twice each (sidebar + card) instead of once
• Redirects verified as 308s: /docs/gateway-and-routing/presets, /docs/gateway-and-routing/byok, /docs/features/presets, /docs/cloud/byok, /docs/models-and-routing/presets, /docs/integrations/openrouter
• Merged main's (guide) tab restructure; the CLI reference move to /docs/usage/cli/* is preserved

🤖 Generated with Claude Code