docs: modernize theme, landing page, and API code samples (#5410)

## Summary

Comprehensive docs overhaul - theme, landing page, API code samples, and
polish.

### Theme (`docs/src/css/custom.css`)
- Inter + JetBrains Mono fonts
- Purple/teal palette, dark mode as default
- Frosted glass navbar, One Dark syntax highlighting
- Tighter sidebar with uppercase category labels
- Better tables: rounded corners, zebra striping, hover highlights
- Hide emoji icons on API category cards

### Landing page (`docs/src/pages/index.js`)
- Dark/light adaptive hero with gradient text
- Endpoint cards in 3-column grid
- Architecture diagram section
- Provider tags by category
- Compact community links
- Fully responsive

### API code samples (`scripts/openapi_generator/code_samples.py`)
- OpenAI Python SDK examples for all 38 stable endpoints via
`x-codeSamples`
- Postinstall patch to hide auto-generated http.client/requests when
custom samples exist
- Only Python (OpenAI) and curl tabs shown (removed Java, NodeJS)
- Fix Batches tag displayName (was showing full description)

### Content fixes
- Add File Processors, Admin, Rerank, Connectors to API overview grid
- Replace oversized buttons with inline links on docs index

### Docusaurus config
- Dark mode default with `respectPrefersColorScheme`
- One Dark code theme via prism-react-renderer

## Test plan

- [x] Previewed locally with `npx docusaurus start`
- [x] Light and dark modes both work
- [x] API code samples show OpenAI Python SDK
- [x] Tables render with new styling
- [x] Pre-commit passes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Signed-off-by: Sébastien Han <seb@redhat.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: leseb

client-sdks/stainless/openapi.yml

@@ -29,10 +29,12 @@ Llama Stack implements the OpenAI API and organizes endpoints by stability level
       title: 'Experimental APIs',
       tone: 'experimental',
       items: [
-        { title: 'Eval', endpoint: 'v1alpha', href: '/docs/api-experimental/eval', blurb: 'Evaluation pipelines and benchmark execution' },
-        { title: 'Benchmarks', endpoint: 'v1alpha', href: '/docs/api-experimental/benchmarks', blurb: 'Benchmark registration and management' },
-        { title: 'Datasets', endpoint: 'v1alpha', href: '/docs/api-experimental/datasets', blurb: 'Dataset management for eval workflows' },
-        { title: 'Dataset IO', endpoint: 'v1alpha', href: '/docs/api-experimental/dataset-io', blurb: 'Dataset read/write operations' },
+        { title: 'Admin', endpoint: '/v1alpha/admin', href: '/docs/api-experimental/llama-stack-specification-experimental-apis', blurb: 'Providers, routes, health, and version' },
+        { title: 'Rerank', endpoint: '/v1alpha/inference/rerank', href: '/docs/api-experimental/rerank-v-1-alpha-inference-rerank-post', blurb: 'Document reranking for search relevance' },
+        { title: 'File Processors', endpoint: '/v1alpha/file_processors', href: '/docs/api-experimental/process-file-v-1-alpha-file-processors-process-post', blurb: 'Document ingestion and chunking' },
+        { title: 'Connectors', endpoint: '/v1beta/connectors', href: '/docs/api-experimental/llama-stack-specification-experimental-apis', blurb: 'External tool and service connectors' },
+        { title: 'Eval', endpoint: '/v1alpha/eval', href: '/docs/api-experimental/eval', blurb: 'Evaluation pipelines and benchmarks' },
+        { title: 'Datasets', endpoint: '/v1beta/datasets', href: '/docs/api-experimental/datasets', blurb: 'Dataset management' },
       ],
     },
     {

docs/docs/api-overview.mdx

@@ -65,38 +65,4 @@ llama stack run
 
 Then connect with any OpenAI-compatible client.
 
-<div style={{display: 'flex', gap: '1rem', flexWrap: 'wrap', margin: '2rem 0'}}>
-  <a href="/docs/getting_started/quickstart"
-     style={{
-       background: 'var(--ifm-color-primary)',
-       color: 'white',
-       padding: '0.75rem 1.5rem',
-       borderRadius: '0.5rem',
-       textDecoration: 'none',
-       fontWeight: 'bold'
-     }}>
-    Quick Start Guide
-  </a>
-  <a href="./api-openai"
-     style={{
-       border: '2px solid var(--ifm-color-primary)',
-       color: 'var(--ifm-color-primary)',
-       padding: '0.75rem 1.5rem',
-       borderRadius: '0.5rem',
-       textDecoration: 'none',
-       fontWeight: 'bold'
-     }}>
-    OpenAI API Compatibility
-  </a>
-  <a href="https://github.com/llamastack/llama-stack"
-     style={{
-       border: '2px solid #666',
-       color: '#666',
-       padding: '0.75rem 1.5rem',
-       borderRadius: '0.5rem',
-       textDecoration: 'none',
-       fontWeight: 'bold'
-     }}>
-    GitHub
-  </a>
-</div>
+[Quick Start Guide](/docs/getting_started/quickstart) | [OpenAI API Compatibility](./api-openai) | [GitHub](https://github.com/llamastack/llama-stack)

docs/docs/index.mdx

@@ -240,16 +240,6 @@ const config: Config = {
         language: "curl",
         logoClass: "curl",
       },
-      {
-        highlight: "javascript",
-        language: "nodejs",
-        logoClass: "nodejs",
-      },
-      {
-        highlight: "java",
-        language: "java",
-        logoClass: "java",
-      },
     ],
   } satisfies Preset.ThemeConfig,
 

docs/docusaurus.config.ts

@@ -16,7 +16,8 @@
     "clean-api-docs": "docusaurus clean-api-docs",
     "gen-api-docs:version": "docusaurus gen-api-docs:version",
     "clean-api-docs:version": "docusaurus clean-api-docs:version",
-    "sync-files": "node scripts/sync-files.js"
+    "sync-files": "node scripts/sync-files.js",
+    "postinstall": "bash scripts/patch-openapi-theme.sh"
   },
   "dependencies": {
     "@docusaurus/core": "^3.9.2",

docs/package-lock.json

@@ -0,0 +1,27 @@
+#!/bin/bash
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+# Patch docusaurus-theme-openapi-docs to hide auto-generated code variants
+# (http.client, requests) when x-codeSamples are provided in the OpenAPI spec.
+# Only the OpenAI SDK examples will show for endpoints that have x-codeSamples.
+FILE="node_modules/docusaurus-theme-openapi-docs/lib/theme/ApiExplorer/CodeSnippets/index.js"
+[ ! -f "$FILE" ] && exit 0
+
+python3 -c "
+with open('$FILE') as f:
+    c = f.read()
+# Skip variants tab when x-codeSamples (samples) exist for this language
+old = '          react_1.default.createElement(\n            CodeTabs_1.default,\n            {\n              className: \"openapi-tabs__code-container-inner\",\n              action: {\n                setLanguage: setLanguage,\n                setSelectedVariant: setSelectedVariant,\n              },\n              includeVariant: true,'
+new = '          !lang.samples && react_1.default.createElement(\n            CodeTabs_1.default,\n            {\n              className: \"openapi-tabs__code-container-inner\",\n              action: {\n                setLanguage: setLanguage,\n                setSelectedVariant: setSelectedVariant,\n              },\n              includeVariant: true,'
+if '!lang.samples &&' not in c:
+    c = c.replace(old, new)
+    with open('$FILE', 'w') as f:
+        f.write(c)
+    print('Patched: x-codeSamples now replace auto-generated variants')
+else:
+    print('Already patched')
+"

docs/package.json

@@ -282,29 +282,68 @@ div[class*='expandButton'] {
 /* Better table styling */
 table {
   display: table;
-  border-collapse: collapse;
+  border-collapse: separate;
+  border-spacing: 0;
   width: 100%;
+  border-radius: 0.75rem;
+  overflow: hidden;
+  border: 1px solid rgba(0, 0, 0, 0.08);
+  margin: 1.5rem 0;
+}
+
+[data-theme='dark'] table {
+  border-color: rgba(255, 255, 255, 0.08);
 }
 
 table th {
-  background: rgba(109, 40, 217, 0.05);
+  background: rgba(109, 40, 217, 0.06);
   font-weight: 600;
-  font-size: 0.85rem;
+  font-size: 0.8rem;
   text-transform: uppercase;
-  letter-spacing: 0.03em;
+  letter-spacing: 0.05em;
+  color: var(--ifm-color-primary);
+  border-bottom: 2px solid rgba(109, 40, 217, 0.12);
 }
 
 [data-theme='dark'] table th {
   background: rgba(167, 139, 250, 0.08);
+  color: var(--ifm-color-primary-light);
+  border-bottom-color: rgba(167, 139, 250, 0.15);
 }
 
 table td, table th {
   padding: 0.75rem 1rem;
-  border: 1px solid rgba(0, 0, 0, 0.06);
+  border-bottom: 1px solid rgba(0, 0, 0, 0.04);
+  border-right: none;
+  border-left: none;
 }
 
-[data-theme='dark'] table td, [data-theme='dark'] table th {
-  border-color: rgba(255, 255, 255, 0.06);
+table tr:last-child td {
+  border-bottom: none;
+}
+
+table tbody tr {
+  transition: background 0.15s;
+}
+
+table tbody tr:hover {
+  background: rgba(109, 40, 217, 0.02);
+}
+
+[data-theme='dark'] table tbody tr:hover {
+  background: rgba(167, 139, 250, 0.04);
+}
+
+[data-theme='dark'] table td {
+  border-bottom-color: rgba(255, 255, 255, 0.04);
+}
+
+table tbody tr:nth-child(even) {
+  background: rgba(0, 0, 0, 0.01);
+}
+
+[data-theme='dark'] table tbody tr:nth-child(even) {
+  background: rgba(255, 255, 255, 0.015);
 }
 
 /* ========== CODE BLOCKS ========== */
@@ -643,3 +682,14 @@ footer.row .col {
 [data-theme='dark'] [class*='yearGroupHeading'] {
   border-bottom-color: rgba(255, 255, 255, 0.06);
 }
+
+/* Hide emoji icons on API doc category cards */
+h2[class*="cardTitle"] {
+  overflow: hidden;
+}
+
+h2[class*="cardTitle"] a {
+  display: block;
+  text-indent: -1.5em;
+  padding-left: 1.5em;
+}

docs/scripts/patch-openapi-theme.sh

@@ -339,7 +339,7 @@
   font-size: 2.2rem;
   font-weight: 700;
   letter-spacing: -0.03em;
-  margin-bottom: 0.5rem;
+  margin-bottom: 0.25rem;
 }
 
 .sectionHead p {
@@ -502,7 +502,7 @@
   font-size: 2rem;
   font-weight: 700;
   letter-spacing: -0.02em;
-  margin-bottom: 0.5rem;
+  margin-bottom: 0.25rem;
 }
 
 .communityInner > p {
@@ -522,15 +522,13 @@
   display: flex;
   flex-direction: column;
   align-items: center;
-  gap: 0.25rem;
-  padding: 1.5rem 1rem;
-  border-radius: 1rem;
+  gap: 0.15rem;
+  padding: 0.75rem 0.75rem;
+  border-radius: 0.5rem;
   border: 1px solid rgba(0, 0, 0, 0.06);
   background: var(--ifm-background-color);
   text-decoration: none !important;
-  transition: all 0.25s ease;
-  backdrop-filter: blur(12px);
-  -webkit-backdrop-filter: blur(12px);
+  transition: all 0.2s;
 }
 
 [data-theme='dark'] .linkCard {
@@ -539,7 +537,7 @@
 }
 
 .linkCard:hover {
-  transform: translateY(-4px);
+  transform: translateY(-1px);
   border-color: var(--ifm-color-primary-lighter);
   box-shadow: 0 12px 32px rgba(109, 40, 217, 0.1);
 }
@@ -553,25 +551,26 @@
   display: flex;
   align-items: center;
   justify-content: center;
-  width: 40px;
-  height: 40px;
-  border-radius: 0.75rem;
+  width: 28px;
+  height: 28px;
+  border-radius: 0.5rem;
+  font-size: 0.85rem;
   background: rgba(109, 40, 217, 0.08);
   color: var(--ifm-color-primary);
-  margin-bottom: 0.5rem;
+  margin-bottom: 0.25rem;
 }
 
 [data-theme='dark'] .linkIcon {
   background: rgba(167, 139, 250, 0.1);
 }
 
 .linkCard strong {
-  font-size: 0.95rem;
+  font-size: 0.85rem;
   color: var(--ifm-font-color-base);
 }
 
 .linkCard span:not(.linkIcon) {
-  font-size: 0.8rem;
+  font-size: 0.7rem;
   color: var(--ifm-font-color-secondary);
 }
 

docs/src/css/custom.css

@@ -11315,7 +11315,7 @@ tags:
 
     Note: This API is currently under active development and may undergo changes.
   name: Batches
-  x-displayName: The Batches API enables efficient processing of multiple requests in a single operation, particularly useful for processing large datasets, batch evaluation workflows, and cost-effective inference at scale.
+  x-displayName: Batches
 - description: ''
   name: Benchmarks
 - description: Protocol for conversation management operations.