@stainless-api/docs 0.1.0-beta.82 → 0.1.0-beta.84

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @stainless-api/docs
 
+## 0.1.0-beta.84
+
+### Minor Changes
+
+- 6ef241e: Sidebar improvements; rename Sidebar to SDKSidebar
+
+### Patch Changes
+
+- d3a85b5: feat: improve not implemented fallback ui
+- 5156697: include markdown alt link for all pages
+- dedd93b: fix incorrect link rel=alternate markdown URLs
+- b532d45: use method summary as page title
+- Updated dependencies [6ef241e]
+- Updated dependencies [d3a85b5]
+- Updated dependencies [d3a85b5]
+- Updated dependencies [2dcb5fb]
+  - @stainless-api/docs-ui@0.1.0-beta.62
+  - @stainless-api/docs-search@0.1.0-beta.15
+
+## 0.1.0-beta.83
+
+### Patch Changes
+
+- 96e974e: clean up n^2 calls to generateDocsRoutes by passing props
+- a0301a2: Improves build speed by up to 8x for large APIs
+- b6b9d30: fix: should hide skipped resources in sidebar
+- Updated dependencies [3037a19]
+  - @stainless-api/ui-primitives@0.1.0-beta.45
+  - @stainless-api/docs-search@0.1.0-beta.14
+  - @stainless-api/docs-ui@0.1.0-beta.61
+
 ## 0.1.0-beta.82
 
 ### Patch Changes

package/eslint-suppressions.json

@@ -11,7 +11,7 @@
   },
   "plugin/cms/server.ts": {
     "@typescript-eslint/no-explicit-any": {
-      "count": 4
+      "count": 3
     }
   },
   "plugin/cms/sidebar-builder.ts": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.82",
+  "version": "0.1.0-beta.84",
   "publishConfig": {
     "access": "public"
   },
@@ -58,9 +58,9 @@
     "vite-plugin-prebundle-workers": "^0.2.0",
     "web-worker": "^1.5.0",
     "yaml": "^2.8.2",
-    "@stainless-api/docs-search": "0.1.0-beta.13",
-    "@stainless-api/docs-ui": "0.1.0-beta.60",
-    "@stainless-api/ui-primitives": "0.1.0-beta.44"
+    "@stainless-api/docs-search": "0.1.0-beta.15",
+    "@stainless-api/docs-ui": "0.1.0-beta.62",
+    "@stainless-api/ui-primitives": "0.1.0-beta.45"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.6",

package/plugin/buildAlgoliaIndex.ts

@@ -74,7 +74,7 @@ export async function buildAlgoliaIndex({
     oas: transformedOAS,
     config,
     languages,
-    version,
+    projectName: version.stainlessProject,
   });
 
   const {

package/plugin/cms/generate-spec.ts

@@ -0,0 +1,112 @@
+import type * as SDKJSON from '@stainless/sdk-json';
+import { Languages } from '@stainless-api/docs-ui/routing';
+import { createSDKJSON, ParsedConfig, parseInputs, transformOAS } from './worker';
+import path from 'path';
+import { readFile, writeFile } from 'fs/promises';
+import { createHash } from 'crypto';
+
+function addAuthToSpec(spec: SDKJSON.Spec, config: ParsedConfig) {
+  const opts = Object.entries(config.client_settings.opts).map(([k, v]) => ({ name: k, ...v }));
+  return {
+    data: spec,
+    auth: spec.security_schemes.map((scheme) => ({
+      ...scheme,
+      opts: opts.filter((opt) => opt.auth?.security_scheme === scheme.name),
+    })),
+  };
+}
+
+type SpecWithAuth = ReturnType<typeof addAuthToSpec>;
+
+function hashStringBase64(input: string, algo = 'sha256') {
+  return createHash(algo).update(input, 'utf8').digest('base64');
+}
+
+class SpecFileSystemCache {
+  private specFilePath: string;
+  private shaForInputsPath: string;
+
+  private hashInputs() {
+    return hashStringBase64(this.currentInputs.oas + this.currentInputs.config);
+  }
+
+  async write(spec: SpecWithAuth) {
+    await writeFile(this.specFilePath, JSON.stringify(spec), 'utf-8');
+    await writeFile(this.shaForInputsPath, this.hashInputs(), 'utf-8');
+    console.log('wrote spec to cache', this.specFilePath);
+  }
+
+  async read() {
+    try {
+      const cachedSha = await readFile(this.shaForInputsPath, 'utf-8');
+      if (cachedSha !== this.hashInputs()) {
+        return null;
+      }
+    } catch {
+      return null;
+    }
+
+    try {
+      const cachedSpec = JSON.parse(await readFile(this.specFilePath, 'utf-8')) as SpecWithAuth;
+      console.log('read spec from cache', this.specFilePath);
+      return cachedSpec;
+    } catch {
+      return null;
+    }
+  }
+
+  constructor(
+    cacheDirectory: string,
+    private currentInputs: { oas: string; config: string },
+  ) {
+    this.specFilePath = path.join(cacheDirectory, 'spec.json');
+    this.shaForInputsPath = path.join(cacheDirectory, 'spec_inputs_sha.txt');
+  }
+}
+
+export async function generateSpecFromStrings({
+  oasStr,
+  configStr,
+  specCacheDirectory,
+  projectName,
+}: {
+  oasStr: string;
+  configStr: string;
+  specCacheDirectory: string | null;
+  projectName: string;
+}) {
+  const fsCache = specCacheDirectory
+    ? new SpecFileSystemCache(specCacheDirectory, { oas: oasStr, config: configStr })
+    : null;
+
+  const cachedSpec = await fsCache?.read();
+  if (cachedSpec) {
+    return cachedSpec;
+  }
+
+  const { oas, config } = await parseInputs({
+    oas: oasStr,
+    config: configStr,
+  });
+
+  const transformedOAS = await transformOAS({ oas, config });
+
+  const languages =
+    config.docs?.languages ??
+    (Object.entries(config.targets)
+      .filter(([name, target]) => Languages.includes(name) && !target.skip)
+      .map(([name]) => name) as SDKJSON.SpecLanguage[]);
+
+  const sdkJson = await createSDKJSON({
+    oas: transformedOAS,
+    config,
+    languages,
+    projectName,
+  });
+
+  const specWithAuth = addAuthToSpec(sdkJson, config);
+
+  await fsCache?.write(specWithAuth);
+
+  return specWithAuth;
+}

package/plugin/cms/server.ts

@@ -3,8 +3,7 @@ import { createServer, IncomingMessage } from 'http';
 import { readFile } from 'fs/promises';
 
 import type * as SDKJSON from '@stainless/sdk-json';
-import { createSDKJSON, parseInputs, transformOAS } from './worker';
-import { Languages, parseRoute, type DocsLanguage } from '@stainless-api/docs-ui/routing';
+import { parseRoute, type DocsLanguage } from '@stainless-api/docs-ui/routing';
 import Stainless, { APIError } from '@stainless-api/sdk';
 
 import {
@@ -14,6 +13,7 @@ import {
 } from './sidebar-builder';
 import type { VersionUserConfig } from '../loadPluginConfig';
 import { bold } from '../../shared/terminalUtils';
+import { generateSpecFromStrings } from './generate-spec';
 export type InputFilePaths = {
   oasPath?: string;
   configPath?: string;
@@ -59,18 +59,22 @@ export type Auth = Array<{
   }[];
 }>;
 
+type LoadedSpec = { data: SDKJSON.Spec; auth: Auth; id: string };
+
 async function loadSpec({
   apiKey,
   devPaths,
   version,
   logger,
+  specCacheDirectory,
 }: {
   apiKey: string;
   devPaths: InputFilePaths;
   version: VersionUserConfig;
   logger: AstroIntegrationLogger;
-}): Promise<{ data: SDKJSON.Spec; auth: Auth; id: string }> {
-  async function unsafeLoad(): Promise<{ data: SDKJSON.Spec; auth: Auth; id: string }> {
+  specCacheDirectory: string | null;
+}): Promise<LoadedSpec> {
+  async function unsafeLoad(): Promise<LoadedSpec> {
     let oasStr: string;
     let configStr: string;
     let versions: Record<DocsLanguage, string> | undefined;
@@ -96,42 +100,25 @@ async function loadSpec({
       configStr = configYML['content'];
     }
 
-    const { oas, config } = await parseInputs({
-      oas: oasStr,
-      config: configStr,
-    });
-
-    const transformedOAS = await transformOAS({ oas, config });
-
-    const languages =
-      config.docs?.languages ??
-      (Object.entries(config.targets)
-        .filter(([name, target]) => Languages.includes(name) && !target.skip)
-        .map(([name]) => name) as SDKJSON.SpecLanguage[]);
-
-    const sdkJson = await createSDKJSON({
-      oas: transformedOAS,
-      config,
-      languages,
-      version,
+    const sdkJson = await generateSpecFromStrings({
+      oasStr,
+      configStr,
+      projectName: version.stainlessProject,
+      specCacheDirectory,
     });
 
     if (versions) {
       for (const [lang, version] of Object.entries(versions)) {
-        const meta = sdkJson.metadata[lang as DocsLanguage];
+        const meta = sdkJson.data.metadata[lang as DocsLanguage];
         if (meta?.version) meta.version = version;
       }
     }
 
     const id = crypto.randomUUID();
-    const opts = Object.entries(config.client_settings.opts).map(([k, v]) => ({ name: k, ...v }));
 
     return {
-      data: sdkJson,
-      auth: sdkJson.security_schemes.map((scheme) => ({
-        ...scheme,
-        opts: opts.filter((opt) => opt.auth?.security_scheme === scheme.name),
-      })),
+      data: sdkJson.data,
+      auth: sdkJson.auth,
       id,
     };
   }
@@ -163,6 +150,7 @@ class Spec {
 
   reload() {
     this.specPromise = loadSpec({
+      specCacheDirectory: this.specCacheDirectory,
       apiKey: this.apiKey,
       devPaths: this.devPaths,
       version: this.version,
@@ -194,8 +182,10 @@ class Spec {
     version: VersionUserConfig,
     devPaths: InputFilePaths,
     private logger: AstroIntegrationLogger,
+    private specCacheDirectory: string | null,
   ) {
     this.specPromise = loadSpec({
+      specCacheDirectory,
       apiKey,
       devPaths,
       version,
@@ -211,7 +201,7 @@ class Spec {
 export type SpecResp = Awaited<ReturnType<Spec['getSpec']>>;
 
 // will be necessary once we add POST methods
-function readJsonBody(req: IncomingMessage): Promise<any> {
+function readJsonBody<T>(req: IncomingMessage): Promise<T> {
   return new Promise((resolve, reject) => {
     let body = '';
     req.on('data', (chunk) => {
@@ -220,7 +210,7 @@ function readJsonBody(req: IncomingMessage): Promise<any> {
     req.on('end', () => {
       try {
         const data = JSON.parse(body);
-        resolve(data);
+        resolve(data as T);
       } catch (error) {
         reject(error);
       }
@@ -228,6 +218,28 @@ function readJsonBody(req: IncomingMessage): Promise<any> {
   });
 }
 
+function markCurrentItems(sidebar: SidebarEntry[], currentSlug: string) {
+  // IMPORTANT: we need to clone the sidebar to avoid mutating the original sidebar
+  const mutableSidebarInstance = structuredClone(sidebar);
+
+  function recursiveMarkCurrent(entries: SidebarEntry[]) {
+    for (const entry of entries) {
+      if (entry.type === 'link') {
+        entry.isCurrent = entry.href === currentSlug;
+        if (entry.isCurrent) {
+          return;
+        }
+      }
+      if (entry.type === 'group') {
+        recursiveMarkCurrent(entry.entries);
+      }
+    }
+  }
+  recursiveMarkCurrent(mutableSidebarInstance);
+
+  return mutableSidebarInstance;
+}
+
 export function startDevServer({
   port,
   version,
@@ -235,15 +247,19 @@ export function startDevServer({
   apiKey,
   getGeneratedSidebarConfig,
   logger,
+  specCacheDirectory,
 }: {
   port: number;
   version: VersionUserConfig;
   devPaths: InputFilePaths;
   apiKey: string;
+  specCacheDirectory: string | null;
   getGeneratedSidebarConfig: (id: number) => GeneratedSidebarConfig | null;
   logger: AstroIntegrationLogger;
 }) {
-  const spec = new Spec(apiKey, version, devPaths, logger);
+  const spec = new Spec(apiKey, version, devPaths, logger, specCacheDirectory);
+
+  const sidebarCache = new Map<string, SidebarEntry[]>();
 
   const server = createServer(async (req, res) => {
     // Add CORS headers
@@ -266,7 +282,7 @@ export function startDevServer({
 
     try {
       if (req.method === 'POST' && req.url === '/retrieve_spec') {
-        const body = await readJsonBody(req);
+        const body = await readJsonBody<{ currentId: string }>(req);
 
         const currentSpec = await spec.getSpec(body.currentId);
 
@@ -275,41 +291,49 @@ export function startDevServer({
 
       if (req.method === 'POST' && req.url === '/build_sidebar') {
         const currentSpec = await spec.forceGetSpec();
-        const body = await readJsonBody(req);
+        const body = await readJsonBody<{ sidebarId: number; basePath: string; currentSlug: string }>(req);
         const sidebarId: number = body.sidebarId;
 
         const sidebarConfig = getGeneratedSidebarConfig(sidebarId);
 
         const sidebarGenerateOptions = sidebarConfig?.options;
 
-        const { stainlessPath: currentStainlessPath, language } = parseRoute(body.basePath, body.currentSlug);
-
-        const configItemsBuilder = new SidebarConfigItemsBuilder(
-          currentSpec.data,
-          language,
-          sidebarGenerateOptions,
-        );
-
-        let userSidebarConfig = configItemsBuilder.generateItems();
-
-        if (sidebarConfig && sidebarConfig.transformFn) {
-          const transformedSidebarConfig = sidebarConfig.transformFn(userSidebarConfig, language);
-          // the user may not have returned, but they may have mutated the config in place
-          // if they did return, we use that
-          if (transformedSidebarConfig) {
-            userSidebarConfig = transformedSidebarConfig;
+        const { language } = parseRoute(body.basePath, body.currentSlug);
+
+        const sidebarCacheKey = `${body.basePath}-${language}-${sidebarId}`;
+
+        const cachedSidebar = sidebarCache.get(sidebarCacheKey);
+        let starlightSidebar: SidebarEntry[] | null = null;
+        if (cachedSidebar) {
+          starlightSidebar = cachedSidebar;
+        } else {
+          const configItemsBuilder = new SidebarConfigItemsBuilder(
+            currentSpec.data,
+            language,
+            sidebarGenerateOptions,
+          );
+
+          let userSidebarConfig = configItemsBuilder.generateItems();
+
+          if (sidebarConfig && sidebarConfig.transformFn) {
+            const transformedSidebarConfig = sidebarConfig.transformFn(userSidebarConfig, language);
+            // the user may not have returned, but they may have mutated the config in place
+            // if they did return, we use that
+            if (transformedSidebarConfig) {
+              userSidebarConfig = transformedSidebarConfig;
+            }
           }
+          starlightSidebar = toStarlightSidebar({
+            basePath: body.basePath,
+            spec: currentSpec.data,
+            entries: userSidebarConfig,
+            currentLanguage: language,
+          });
+
+          sidebarCache.set(sidebarCacheKey, starlightSidebar);
         }
-        const starlightSidebar = toStarlightSidebar({
-          basePath: body.basePath,
-          currentSlug: body.currentSlug,
-          spec: currentSpec.data,
-          entries: userSidebarConfig,
-          currentStainlessPath,
-          currentLanguage: language,
-        });
 
-        return respond(200, { data: starlightSidebar });
+        return respond(200, { data: markCurrentItems(starlightSidebar, body.currentSlug) });
       }
 
       return respond(404, { message: 'Not found' });
@@ -325,6 +349,7 @@ export function startDevServer({
   return {
     invalidate: () => {
       spec.reload();
+      sidebarCache.clear();
     },
     destroy: function destroy() {
       return new Promise<void>((resolve) => {

package/plugin/cms/sidebar-builder.ts

@@ -273,6 +273,7 @@ type SidebarEntry = StarlightRouteData['sidebar'][number];
 
 // This allows us to be a bit more forgiving to the user.
 // As long as they don't modify the key, we can still find the item.
+
 function getResourceOrMethod(spec: SDKJSON.Spec, endpointOrConfigRef: string) {
   for (const entry of walkTree(spec, false)) {
     if (entry.data.kind === 'resource' && entry.data.configRef === endpointOrConfigRef) {
@@ -306,19 +307,17 @@ export type BuildSidebarParams = {
   currentSlug: string;
 };
 
-type ToStarlightSidebarParams = BuildSidebarParams & {
+type ToStarlightSidebarParams = {
+  basePath: string;
   spec: SDKJSON.Spec;
   entries: ReferenceSidebarConfigItem[];
-  currentStainlessPath: string;
   currentLanguage: DocsLanguage;
 };
 
 export function toStarlightSidebar({
   basePath,
-  currentSlug,
   spec,
   entries,
-  currentStainlessPath,
   currentLanguage,
 }: ToStarlightSidebarParams): SidebarEntry[] {
   const starlightEntries: SidebarEntry[] = [];
@@ -331,7 +330,7 @@ export function toStarlightSidebar({
         type: 'link',
         href: readmeSlug,
         label: entry.label,
-        isCurrent: currentSlug === readmeSlug,
+        isCurrent: false,
         badge: entry.badge,
         attrs: {
           'data-stldocs-overview': 'readme',
@@ -350,14 +349,12 @@ export function toStarlightSidebar({
         language: currentLanguage,
       });
 
-      const isCurrent = resourceOrMethod.data.stainlessPath === currentStainlessPath;
-
       if (resourceOrMethod.data.kind === 'http_method') {
         starlightEntries.push({
           type: 'link',
           href: route,
           label: entry.label,
-          isCurrent,
+          isCurrent: false,
           badge: entry.badge,
           attrs: {
             'data-stldocs-method': resourceOrMethod.data.httpMethod,
@@ -368,7 +365,7 @@ export function toStarlightSidebar({
           type: 'link',
           href: route,
           label: entry.label,
-          isCurrent,
+          isCurrent: false,
           badge: entry.badge,
           attrs: {
             // TODO: @Ryan: is data.name unique? This is what we used before so I'm not changing, but I am curious.
@@ -379,14 +376,20 @@ export function toStarlightSidebar({
         throw new Error(`Unknown entry kind ${JSON.stringify(entry)}`);
       }
     } else if (entry.kind === 'group') {
+      // Skip pushing the group if if the resource it represents is not available in the current language.
+      // This occurs when SDK generation for the current language is skipped in the Stainless config for that resource.
+      if (entry.resourceGroupKey) {
+        const resourceOrMethod = getResourceOrMethod(spec, entry.resourceGroupKey);
+        if (resourceOrMethod?.data?.kind === 'resource' && !resourceOrMethod?.data?.[currentLanguage]) {
+          continue;
+        }
+      }
       starlightEntries.push({
         type: 'group',
         label: entry.label,
         entries: toStarlightSidebar({
           basePath,
-          currentSlug,
           spec,
-          currentStainlessPath,
           entries: entry.entries,
           currentLanguage,
         }),

package/plugin/cms/worker.ts

@@ -5,7 +5,6 @@ import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 import fs from 'fs/promises';
 import pathutils from 'path';
-import type { VersionUserConfig } from '../loadPluginConfig';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -161,12 +160,12 @@ export async function createSDKJSON({
   oas,
   config,
   languages,
-  version,
+  projectName,
 }: {
   oas: OpenAPIDocument;
   config: ParsedConfig;
   languages: DocsLanguage[];
-  version: VersionUserConfig;
+  projectName: string;
 }) {
   const templatePath = resolve(__dirname, '../vendor/templates');
   const readmeLoader = await Promise.all(
@@ -191,7 +190,7 @@ export async function createSDKJSON({
       config,
       languages,
       transform: false,
-      projectName: version.stainlessProject,
+      projectName,
       readmeTemplates,
     },
   });

package/plugin/helpers/generateDocsRoutes.ts

@@ -15,7 +15,7 @@ export function generateDocsRoutes(spec: SDKJSON.Spec, excludeLanguages: DocsLan
       stainlessPath: null,
       language: language as DocsLanguage,
       title: 'Readme',
-      kind: 'readme',
+      kind: 'readme' as const,
     }));
 
   return [...paths, ...readmes].map(({ slug, stainlessPath, language, title, kind }) => {

package/plugin/index.ts

@@ -4,7 +4,7 @@ import type { AstroIntegration, AstroIntegrationLogger } from 'astro';
 import type { BundledTheme } from 'shiki';
 import { config } from 'dotenv';
 import getPort from 'get-port';
-import { startDevServer, type SpecResp } from './cms/server';
+import { DevSpecServer, startDevServer, type SpecResp } from './cms/server';
 import { buildAlgoliaIndex } from './buildAlgoliaIndex';
 import {
   getAPIReferencePlaceholderItemFromSidebarConfig,
@@ -30,6 +30,7 @@ import { resolveSrcFile } from '../resolveSrcFile';
 import { mkdir, writeFile } from 'fs/promises';
 import { fileURLToPath } from 'url';
 import prebundleWorkers from 'vite-plugin-prebundle-workers';
+import { generateMissingRouteList } from '@stainless-api/docs-ui/routing';
 
 export { generateAPILink } from './generateAPIReferenceLink';
 export type { ReferenceSidebarConfigItem };
@@ -130,20 +131,7 @@ async function stlStarlightAstroIntegration(
 
   const { apiKey, version, devPaths } = tmpGetCMSServerConfig(pluginConfig.specRetrieverConfig);
 
-  const cmsServer = startDevServer({
-    port: CMS_PORT,
-    apiKey: apiKey.value,
-    version,
-    devPaths,
-    logger: stlStarlightPluginLogger,
-    getGeneratedSidebarConfig: (id: number) => {
-      const config = sidebarConfigs.get(id);
-      if (!config) {
-        return null;
-      }
-      return config;
-    },
-  });
+  let cmsServer: DevSpecServer | undefined;
 
   let building: Promise<void> | undefined;
   let reportError: ((message: string) => void) | null = null;
@@ -186,11 +174,36 @@ async function stlStarlightAstroIntegration(
         logger: localLogger,
         command,
         config: astroConfig,
+        createCodegenDir,
       }) => {
         const logger = getSharedLogger({ fallback: localLogger });
         const projectDir = astroConfig.root.pathname;
         astroBase = astroConfig.base;
 
+        const codegenDir = createCodegenDir().pathname;
+
+        let specCacheDirectory: string | null = null;
+        if (command === 'dev') {
+          specCacheDirectory = path.join(codegenDir, 'spec_cache');
+          fs.mkdirSync(specCacheDirectory, { recursive: true });
+        }
+
+        cmsServer = startDevServer({
+          port: CMS_PORT,
+          apiKey: apiKey.value,
+          version,
+          devPaths,
+          logger: stlStarlightPluginLogger,
+          specCacheDirectory,
+          getGeneratedSidebarConfig: (id: number) => {
+            const config = sidebarConfigs.get(id);
+            if (!config) {
+              return null;
+            }
+            return config;
+          },
+        });
+
         reportError = (message: string) => logger.error(message);
 
         if (pluginConfig.experimentalPlaygrounds) {
@@ -248,7 +261,7 @@ async function stlStarlightAstroIntegration(
                   server.watcher.on('change', async (changed) => {
                     if (Object.values(devPaths).includes(changed)) {
                       logger.info(`${changed} changed, reloading...`);
-                      cmsServer.invalidate();
+                      cmsServer?.invalidate();
                       server.hot.send({
                         type: 'full-reload',
                         path: '*',
@@ -341,7 +354,7 @@ async function stlStarlightAstroIntegration(
         });
       },
       'astro:server:done': async () => {
-        await cmsServer.destroy();
+        await cmsServer?.destroy();
       },
       'astro:build:start'({ logger }) {
         collectedErrors = [];
@@ -365,6 +378,31 @@ async function stlStarlightAstroIntegration(
           astroBase,
         };
         await writeFile(path.join(stainlessDir, 'stl-manifest.json'), JSON.stringify(manifest, null, 2));
+
+        // Generate a list of missing API routes to enable graceful handling of unimplemented SDK methods.
+        // When users switch languages in the docs, some API methods may not be implemented in the target SDK.
+        // Instead of showing a generic 404, we statically generate pages for these routes and mark them
+        // in this file so Cloudflare can serve them with a 404 status. These pages display helpful information
+        // about the missing method and provide links to SDKs where it is available.
+        const { data: spec } = (await (
+          await fetch(`http://localhost:${CMS_PORT}/retrieve_spec`, {
+            method: 'POST',
+            body: JSON.stringify({}),
+          })
+        ).json()) as SpecResp;
+        if (spec) {
+          const missingRoutes = await generateMissingRouteList({
+            spec,
+            basePath: path.posix.join(astroBase, pluginConfig.basePath),
+          });
+          await mkdir(stainlessDir, { recursive: true });
+          await writeFile(
+            path.join(stainlessDir, 'missing-routes.json'),
+            JSON.stringify(missingRoutes, null, 2),
+          );
+        } else {
+          console.log('Could not retrieve spec for missing routes check');
+        }
       },
     },
   };
@@ -397,6 +435,7 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
           }
           process.exit(1);
         }
+
         const config = configParseResult.config;
 
         const isReactLoaded = astroConfig.integrations.find(({ name }) => name === '@astrojs/react');

package/plugin/routes/Docs.astro

@@ -3,8 +3,8 @@ import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
 import { cmsClient } from '../cms/client';
 import { getReadmeContent, buildPageNavigation, RenderSpec, astroMarkdownRender } from '../react/Routing';
 import { getResourceFromSpec } from '@stainless-api/docs-ui/utils';
+import { parseStainlessPath } from '@stainless-api/docs-ui/routing';
 import {
-  BASE_PATH,
   CONTENT_PANEL_LAYOUT,
   MIDDLEWARE,
   EXPERIMENTAL_REQUEST_BUILDER,
@@ -13,55 +13,58 @@ import { generateDocsRoutes } from '../helpers/generateDocsRoutes';
 import { StainlessIslands } from '../components/StainlessIslands';
 
 const spec = await cmsClient.getSpec();
-const routes = generateDocsRoutes(spec);
 
-const route = routes.find((r) => r.params.slug === Astro.params.slug);
+export type Props = Awaited<ReturnType<typeof generateDocsRoutes>>[number]['props'] | Record<string, never>;
 
-if (!route) {
-  throw new Error(`Could not find a route for slug '${Astro.params.slug}'`);
-}
+const props =
+  'language' in Astro.props
+    ? // In prod, we pass the props down to this page
+      Astro.props
+    : // In the dev server, we skip the DocsStatic wrapper so we need to find the props ourselves
+      generateDocsRoutes(spec).find((r) => r.params.slug === Astro.params.slug)?.props;
+if (!props) throw new Error(`Could not find a route for slug '${Astro.params.slug}'`);
 
 // PageTitle override will skip rendering the default Starlight title
 Astro.locals._stlStarlightPage = {
-  skipRenderingStarlightTitle: route.props.kind === 'readme' ? false : true,
+  skipRenderingStarlightTitle: props.kind === 'readme' ? false : true,
 };
 
-const readmeContent = await getReadmeContent(spec, route.props.language);
-const readme = route.props.kind === 'readme' ? await astroMarkdownRender(readmeContent ?? '') : null;
+const readmeContent = await getReadmeContent(spec, props.language);
+const readme = props.kind === 'readme' ? await astroMarkdownRender(readmeContent ?? '') : null;
 
-const resource = route.props.stainlessPath ? getResourceFromSpec(route.props.stainlessPath, spec) : null;
+const resource = props.stainlessPath ? getResourceFromSpec(props.stainlessPath, spec) : null;
 
 const pageNav =
-  route.props.kind === 'resource' && resource
+  props.kind === 'resource' && resource
     ? buildPageNavigation(resource)
-    : route.props.kind === 'readme' && readme?.metadata
+    : props.kind === 'readme' && readme?.metadata
       ? readme?.metadata.headings
       : [];
 
-const props = route.props;
 Astro.locals.language = props.language;
 
+// Use first heading in README as page title
 if (readme) {
   const repo = spec.metadata?.[props.language]?.code_url;
   readme.code = readme.code.replace(/<a href="(?!(?:https?:\/\/|\/\/))([^"]+)"/g, `<a href="${repo}/$1"`);
   props.title = readme.metadata.headings[0]!.text ?? 'Overview';
 }
+
+// use summary for the page title of method pages
+if (props.kind === 'http_method' && props.stainlessPath) {
+  const parsed = parseStainlessPath(props.stainlessPath);
+  const resource = getResourceFromSpec(props.stainlessPath, spec);
+  if (parsed?.method && resource?.methods[parsed.method]) {
+    const method = resource.methods[parsed.method];
+    props.title = method?.summary ?? method?.title ?? props.title;
+  }
+}
 ---
 
 <StarlightPage
   headings={pageNav}
   frontmatter={{
-    title: props?.title,
-    head: [
-      {
-        tag: 'link',
-        attrs: {
-          rel: 'alternate',
-          type: 'text/markdown',
-          href: `${BASE_PATH}/${Astro.params.slug}.md`,
-        },
-      },
-    ],
+    title: props.title,
     pagefind: false,
     tableOfContents: ['resource', 'readme'].includes(props.kind) ? { maxHeadingLevel: 6 } : false,
   }}

package/plugin/routes/DocsStatic.astro

@@ -9,6 +9,9 @@ export const getStaticPaths = (async () => {
   const routes = generateDocsRoutes(spec);
   return routes;
 }) satisfies GetStaticPaths;
+
+export type Props = Awaited<ReturnType<typeof getStaticPaths>>[number]['props'];
+const props = Astro.props;
 ---
 
-<Docs />
+<Docs {...props} />

package/plugin/routes/markdown.ts

@@ -55,3 +55,5 @@ export const GET: APIRoute<RouteProps> = async ({ props }) => {
     headers: { 'Content-Type': 'text/plain' },
   });
 };
+
+export const prerender = true;

package/stl-docs/components/Head.astro

@@ -1,14 +1,16 @@
 ---
 import Default from '@astrojs/starlight/components/Head.astro';
-
+import path from 'path';
 // TODO: for users who are overriding the font stack in their own styles, how can we know that and
 // preload their font instead of ours?
 import geistPath from '../../assets/fonts/geist/geist-latin.woff2';
+
+const mdPath = path.posix.join(Astro.url.pathname, 'index.md');
 ---
 
 <Default />
-
 <link rel="preload" as="font" type="font/woff2" crossorigin="anonymous" href={geistPath} />
+<link rel="alternate" type="text/markdown" href={mdPath} />
 
 <script>
   import { wireAIDropdown } from '../../plugin/globalJs/ai-dropdown-options.ts';

package/stl-docs/components/sidebars/BaseSidebar.astro

@@ -1,10 +1,15 @@
 ---
-import Default from '@astrojs/starlight/components/Sidebar.astro';
 import HeaderLinks from '../headers/HeaderLinks.astro';
+import { SidebarWithComponents } from './SidebarWithComponents';
+import SidebarPersister from '@astrojs/starlight/components/SidebarPersister.astro';
+
+const { sidebar } = Astro.locals.starlightRoute;
 ---
 
 <div class="stl-sidebar-header-links">
   <HeaderLinks />
 </div>
 <slot name="sdk-select" />
-<Default><slot /></Default>
+<SidebarPersister>
+  <SidebarWithComponents entries={sidebar} withStarlightRestoration />
+</SidebarPersister>

package/stl-docs/components/sidebars/SidebarWithComponents.tsx

@@ -0,0 +1,10 @@
+import { StlSidebar, StlSidebarProps } from '@stainless-api/docs-ui/components';
+import { ComponentProvider } from '@stainless-api/docs-ui/contexts/component';
+
+export function SidebarWithComponents(props: StlSidebarProps) {
+  return (
+    <ComponentProvider>
+      <StlSidebar {...props} />
+    </ComponentProvider>
+  );
+}

package/styles/page.css

@@ -35,7 +35,9 @@
   /* on desktop, adjust sidebar so that its _text content_ aligns with the page left edge.
    * padding (visible on hover) bleeds out beyond the page left edge, covered by --stl-ui-page-padding-inline */
   .sidebar-pane {
-    margin-inline-start: calc(-1 * (var(--sl-sidebar-pad-x) + var(--stl-sidebar-item-padding-inline)));
+    /* 12px comes from --stl-sidebar-item-padding-inline (which is unfortunately defined deeper than
+    this component). Please keep in sync. */
+    margin-inline-start: calc(-1 * (var(--sl-sidebar-pad-x) + 12px));
   }
 
   .header,

package/styles/sidebar.css

@@ -11,220 +11,10 @@
   }
 }
 
-.sidebar {
-  --stl-sidebar-item-padding-inline: 12px;
-  --stl-sidebar-item-padding-block: 6px;
-  --stl-sidebar-indent: 12px;
-  font-size: var(--stl-typography-scale-sm);
-}
-
 .sidebar-pane {
   border-inline-end: 1px solid var(--stl-color-border-faint);
 }
 
-.sidebar-content {
-  ul,
-  summary {
-    list-style-type: none;
-  }
-
-  /* collapsible sections */
-  details > summary {
-    display: flex;
-    align-items: center;
-    font-weight: 500;
-
-    .caret {
-      margin-left: auto;
-      margin-right: -4px;
-      opacity: 0.65;
-      transition:
-        opacity 0.1s ease-out,
-        transform 0.1s ease-out;
-    }
-  }
-  details[open] > summary .caret {
-    opacity: 1;
-    transform: rotate(90deg);
-  }
-
-  /* list items */
-  summary,
-  li {
-    margin: 0;
-    border-radius: 8px;
-  }
-  summary,
-  li a {
-    cursor: pointer;
-    padding: var(--stl-sidebar-item-padding-block) var(--stl-sidebar-item-padding-inline);
-    &:hover,
-    &[aria-current='page'] {
-      color: var(--stl-color-foreground);
-    }
-  }
-
-  li a {
-    color: var(--stl-color-foreground-reduced);
-    font-weight: 400;
-    display: flex;
-    text-decoration: none;
-    span {
-      font-weight: inherit;
-    }
-
-    &:hover {
-      text-decoration: underline;
-      text-decoration-color: var(--stl-color-foreground-reduced);
-    }
-    &[aria-current='page'] {
-      font-weight: 500;
-    }
-  }
-  li:has(> a:is(:hover, [aria-current='page'])),
-  summary:hover {
-    background-color: var(--stl-color-background-hover);
-  }
-
-  /* nested list items have flat left edge */
-  ul ul :is(summary, li) {
-    border-start-start-radius: 0;
-    border-end-start-radius: 0;
-  }
-  ul {
-    padding: 0;
-  }
-  ul ul li {
-    border-inline-start: 1px solid var(--stl-color-border-faint);
-    margin-inline-start: var(--stl-sidebar-indent);
-    &:has(> a[aria-current='page']) {
-      border-inline-start: 2px solid var(--stl-color-accent-border-strong);
-      & > a {
-        margin-left: -1px;
-      }
-    }
-  }
-
-  /* Method & resource icons */
-
-  a[data-stldocs-method],
-  a[data-stldocs-resource] {
-    --stl-ui-sidebar-icon-size-outer: 18px;
-    --stl-ui-sidebar-icon-margin: 8px;
-  }
-  a[data-stldocs-method] {
-    --stl-ui-sidebar-icon-size-inner: 16px;
-    --stl-ui-sidebar-icon-color-inverse-background: var(--stl-ui-sidebar-icon-color);
-
-    &[data-stldocs-method='get'] {
-      --stl-ui-sidebar-icon-color: var(--stl-color-green-foreground);
-      --stl-ui-sidebar-icon-color-border: var(--stl-color-green-border);
-      --stl-ui-sidebar-icon-color-background: var(--stl-color-green-muted-background);
-      --stl-ui-sidebar-icon-color-background-hover: var(--stl-color-green-muted-background-hover);
-      --stl-ui-sidebar-icon-color-inverse-background: var(--stl-color-green-inverse-background);
-      --stl-ui-sidebar-icon-color-inverse-foreground: var(--stl-color-green-inverse-foreground);
-    }
-    &[data-stldocs-method='post'] {
-      --stl-ui-sidebar-icon-color: var(--stl-color-blue-foreground);
-      --stl-ui-sidebar-icon-color-border: var(--stl-color-blue-border);
-      --stl-ui-sidebar-icon-color-background: var(--stl-color-blue-muted-background);
-      --stl-ui-sidebar-icon-color-background-hover: var(--stl-color-blue-muted-background-hover);
-      --stl-ui-sidebar-icon-color-inverse-background: var(--stl-color-blue-inverse-background);
-      --stl-ui-sidebar-icon-color-inverse-foreground: var(--stl-color-blue-inverse-foreground);
-    }
-    &[data-stldocs-method='patch'],
-    &[data-stldocs-method='put'] {
-      --stl-ui-sidebar-icon-color: var(--stl-color-orange-foreground);
-      --stl-ui-sidebar-icon-color-border: var(--stl-color-orange-border);
-      --stl-ui-sidebar-icon-color-background: var(--stl-color-orange-muted-background);
-      --stl-ui-sidebar-icon-color-background-hover: var(--stl-color-orange-muted-background-hover);
-      --stl-ui-sidebar-icon-color-inverse-background: var(--stl-color-orange-inverse-background);
-      --stl-ui-sidebar-icon-color-inverse-foreground: var(--stl-color-orange-inverse-foreground);
-    }
-    &[data-stldocs-method='delete'] {
-      --stl-ui-sidebar-icon-color: var(--stl-color-red-foreground);
-      --stl-ui-sidebar-icon-color-border: var(--stl-color-red-border);
-      --stl-ui-sidebar-icon-color-background: var(--stl-color-red-muted-background);
-      --stl-ui-sidebar-icon-color-background-hover: var(--stl-color-red-muted-background-hover);
-      --stl-ui-sidebar-icon-color-inverse-background: var(--stl-color-red-inverse-background);
-      --stl-ui-sidebar-icon-color-inverse-foreground: var(--stl-color-red-inverse-foreground);
-    }
-
-    &[data-stldocs-method='get'] {
-      --stl-ui-sidebar-icon-url: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="black" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M17 7 7 17"/><path d="M17 17H7V7"/></svg>');
-    }
-    &[data-stldocs-method='post'],
-    &[data-stldocs-method='put'],
-    &[data-stldocs-method='patch'] {
-      --stl-ui-sidebar-icon-url: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="black" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M7 7h10v10"/><path d="M7 17 17 7"/></svg>');
-    }
-    &[data-stldocs-method='delete'] {
-      --stl-ui-sidebar-icon-url: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="black" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 6 6 18"/><path d="m6 6 12 12"/></svg>');
-    }
-  }
-
-  a[data-stldocs-resource] {
-    /* not yet implemented in markup */
-    --stl-ui-sidebar-icon-color: var(--stl-color-foreground-muted);
-    --stl-ui-sidebar-icon-color-border: var(--stl-color-border);
-    --stl-ui-sidebar-icon-color-background: var(--stl-color-faint-background);
-    --stl-ui-sidebar-icon-color-background-hover: var(--stl-color-faint-background-hover);
-    --stl-ui-sidebar-icon-color-inverse-background: var(--stl-color-inverse-background);
-    --stl-ui-sidebar-icon-color-inverse-foreground: var(--stl-color-inverse-foreground);
-
-    --stl-ui-sidebar-icon-size-inner: 14px;
-    --stl-ui-sidebar-icon-url: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="black" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M8 3H7a2 2 0 0 0-2 2v5a2 2 0 0 1-2 2 2 2 0 0 1 2 2v5c0 1.1.9 2 2 2h1"/><path d="M16 21h1a2 2 0 0 0 2-2v-5c0-1.1.9-2 2-2a2 2 0 0 1-2-2V5a2 2 0 0 0-2-2h-1"/></svg>');
-  }
-
-  a[data-stldocs-method],
-  a[data-stldocs-resource] {
-    display: flex;
-    gap: var(--stl-ui-sidebar-icon-margin);
-    align-items: center;
-    position: relative;
-
-    &::before,
-    &::after {
-      content: '';
-      width: var(--stl-ui-sidebar-icon-size-outer);
-      height: var(--stl-ui-sidebar-icon-size-outer);
-      display: block;
-    }
-    &::before {
-      border-radius: 4px;
-      background-color: var(--stl-ui-sidebar-icon-color-background);
-      flex: 0 0 auto;
-      border: 1px solid var(--stl-ui-sidebar-icon-color-border, transparent);
-    }
-    /* yuck (we can clean this up once we are changing sidebar markup) */
-    &::after {
-      background-color: var(--stl-ui-sidebar-icon-color);
-      mask-image: var(--stl-ui-sidebar-icon-url);
-      mask-size: var(--stl-ui-sidebar-icon-size-inner) var(--stl-ui-sidebar-icon-size-inner);
-      mask-repeat: no-repeat;
-      mask-position: center;
-      position: absolute;
-      left: var(--stl-sidebar-item-padding-inline);
-      top: 50%;
-      transform: translateY(-50%);
-    }
-
-    &:hover {
-      &::before {
-        background-color: var(--stl-ui-sidebar-icon-color-background-hover);
-      }
-    }
-    &[aria-current='page'] {
-      &::before {
-        background-color: var(--stl-ui-sidebar-icon-color-inverse-background);
-      }
-      &::after {
-        background-color: var(--stl-ui-sidebar-icon-color-inverse-foreground);
-      }
-    }
-  }
-}
-
 .sidebar-content .stl-mobile-only-sidebar-item-last {
   margin-bottom: 2rem;
   position: relative;

package/theme.css

@@ -23,3 +23,4 @@
 @import '@stainless-api/docs-ui/styles/primitives.css';
 @import '@stainless-api/docs-ui/styles/main.css';
 @import '@stainless-api/docs-ui/styles/search.css';
+@import '@stainless-api/docs-ui/styles/sidebar.css';