docs: add first‑class API Reference to Jan docs (Local + Server)

[ramonpzg]

This PR Introduces an interactive API Reference to Jan docs with clean Scalar integration, consistent navigation, and a robust CI flow to keep cloud specs up to date.

What’s included

• API Reference
  • New reference page at /api with entry points for:
    • Local API (llama.cpp): /api-reference/local
    • Jan Server API (vLLM): /api-reference/cloud
  • Scalar integration with minimal overrides (native styling preserved)
  • Theme sync (light/dark); fixes light-mode logo visibility
  • “Try It Out” supports custom server URL (input, URL param, localStorage) 🙌
  • Auth optional for Local; enforced for Server
• Navigation
  • Adds Docs ⇄ API Reference nav to regular docs (left of header; no duplication on API pages)
  • API pages use their own layout; regular docs inject nav via config
  • Centralized, scalable pattern for multi-product docs
• Cloud spec sync (CI/CD)
  • New workflow: .github/workflows/update-cloud-api-spec.yml
    • Manual trigger, webhook, and daily scheduled sync (2 AM UTC)
    • Creates PR or commits directly (configurable)
  • jan-astro-docs.yml updated to conditionally use existing spec for PR/push builds
  • New script: website/scripts/conditional-cloud-spec.js (safe, conditional updates)
  • generate-cloud-spec.js updated (FORCE_UPDATE support, better logs)
• Docs layout cohesion
  • Main index remains the mission hub; API Reference is now first-class and discoverable
  • Clear paths for future Browser Extension and Server docs to adopt the same nav pattern. This is really important to keep all docs synchronized with minimal effort

Jan Server

Jan Local

Developer notes

• Local: bun run api:local or bun run api:dev
• Force-refresh cloud spec locally: bun run generate:cloud-spec-force
• Custom server for Try It Out: use the input field or ?server=http://host:port
• CI daily sync keeps cloud-openapi.json current; manual trigger available for Server team

Validation

• Built site locally; verified API pages, Try It Out, theme switching, and nav active states
• CI build path tested with conditional spec generation
• Confirmed no nav duplication on API pages; visible in regular docs only

Risks / Rollout

• Cloud spec source outage: build falls back to last good spec (no build break)
• If removing legacy scripts/workflows, confirm no external jobs still depend on them

Impact

• Makes our OpenAI-compatible API a first-class citizen
• Aligns docs with Jan’s ecosystem narrative
• Reduces styling debt and improves maintainability
• Establishes a dependable, auditable spec update pipeline

[ellipsis-dev]

⚠️ This PR is too big for Ellipsis, but support for larger PRs is coming soon. If you want us to prioritize this feature, let us know at [email protected]

---

Generated with ❤️ by ellipsis.dev

[github-actions]

Preview URL Astro Docs: https://68c1fa0e.astro-docs-14t.pages.dev

[github-actions]

🌐 Preview available: https://pr-3d981591f8c76cbe040059c902cc0a8da9a74298-jan-server-web.menlo.ai

[github-actions]

🌐 Preview available: https://pr-30cae084a284b8bc3e0882450b2eaddd06f4fa73-jan-server-web.menlo.ai

[github-actions]

🌐 Preview available: https://pr-ff48743e2f13de4a1c55210f5197fa86838361f0-jan-server-web.menlo.ai