@stainless-api/docs 0.1.0-beta.88 → 0.1.0-beta.89

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @stainless-api/docs
 
+## 0.1.0-beta.89
+
+### Minor Changes
+
+- 4b2bd1c: Adds Webhook events overview page
+
+### Patch Changes
+
+- 7bda782: fix bug when detecting current sidebar item
+- de83f02: fix api reference base path
+- 31457f3: support for setting custom fonts
+- Updated dependencies [31457f3]
+  - @stainless-api/ui-primitives@0.1.0-beta.47
+  - @stainless-api/docs-search@0.1.0-beta.20
+  - @stainless-api/docs-ui@0.1.0-beta.67
+
 ## 0.1.0-beta.88
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.88",
+  "version": "0.1.0-beta.89",
   "publishConfig": {
     "access": "public"
   },
@@ -14,7 +14,6 @@
     "./plugin/languages": "./plugin/languages.ts",
     "./stainless-docs/mintlify-compat": "./stl-docs/components/mintlify-compat/index.ts",
     "./mintlify-compat.css": "./styles/mintlify-compat.css",
-    "./font-imports": "./styles/fonts.css",
     "./components": "./stl-docs/components/index.ts",
     "./components/scripts": "./stl-docs/components/scripts.ts",
     "./docs-config": "./stl-docs/loadStlDocsConfig.ts",
@@ -57,9 +56,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.19",
-    "@stainless-api/docs-ui": "0.1.0-beta.66",
-    "@stainless-api/ui-primitives": "0.1.0-beta.46"
+    "@stainless-api/docs-search": "0.1.0-beta.20",
+    "@stainless-api/docs-ui": "0.1.0-beta.67",
+    "@stainless-api/ui-primitives": "0.1.0-beta.47"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.6",

package/plugin/components/SDKSelect.astro

@@ -1,14 +1,19 @@
 ---
 import { parseRoute } from '@stainless-api/docs-ui/routing';
-import { BASE_PATH, DEFAULT_LANGUAGE, EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
+import {
+  RESOLVED_API_REFERENCE_PATH,
+  DEFAULT_LANGUAGE,
+  EXCLUDE_LANGUAGES,
+} from 'virtual:stl-starlight-virtual-module';
 import { Languages } from '../languages';
 import { SDKSelectReactComponent } from '../react/Routing';
 import { getSDKJSONInSSR } from '../specs/fetchSpecSSR';
 import { getDocsLanguages } from '../helpers/getDocsLanguages';
+import { API_REFERENCE_BASE_PATH } from 'virtual:stl-docs-virtual-module';
 
 const slug = `/${Astro.locals.starlightRoute.id}`;
 
-const basePath = BASE_PATH;
+const basePath = API_REFERENCE_BASE_PATH;
 const defaultLanguage = DEFAULT_LANGUAGE;
 const { language, stainlessPath } = parseRoute(basePath, slug);
 
@@ -27,7 +32,8 @@ const options = getDocsLanguages(spec, EXCLUDE_LANGUAGES).map((value) => ({
   selected: data.language === value,
 }));
 
-const readmeSlug = language === 'http' ? BASE_PATH : `${BASE_PATH}/${language}`;
+const readmeSlug =
+  language === 'http' ? RESOLVED_API_REFERENCE_PATH : `${RESOLVED_API_REFERENCE_PATH}/${language}`;
 ---
 
 <span
@@ -52,7 +58,7 @@ const readmeSlug = language === 'http' ? BASE_PATH : `${BASE_PATH}/${language}`;
   import { navigate } from 'astro:transitions/client';
   import { updateSelectedLanguage } from '../languages';
   import { initDropdown } from '@stainless-api/docs/components/scripts';
-  import { BASE_PATH } from 'virtual:stl-starlight-virtual-module';
+  import { RESOLVED_API_REFERENCE_PATH } from 'virtual:stl-starlight-virtual-module';
   import { getPageLoadEvent } from '../helpers/getPageLoadEvent';
 
   document.addEventListener(getPageLoadEvent(), () => {
@@ -62,7 +68,7 @@ const readmeSlug = language === 'http' ? BASE_PATH : `${BASE_PATH}/${language}`;
       root: sdkSelect,
       onSelect: (value) => {
         const originalLanguage = sdkSelect.dataset.currentValue;
-        navigate(updateSelectedLanguage(BASE_PATH, originalLanguage, value));
+        navigate(updateSelectedLanguage(RESOLVED_API_REFERENCE_PATH, originalLanguage, value));
       },
     });
   });

package/plugin/components/search/SearchIsland.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { BASE_PATH, HIGHLIGHT_THEMES } from 'virtual:stl-starlight-virtual-module';
+import { RESOLVED_API_REFERENCE_PATH, HIGHLIGHT_THEMES } from 'virtual:stl-starlight-virtual-module';
 import { parseRoute, generateRoute } from '@stainless-api/docs-ui/routing';
 import { SearchModal } from '@stainless-api/docs-search';
 import * as Markdoc from '@markdoc/markdoc';
@@ -63,7 +63,7 @@ async function createMarkdownRenderer(): Promise<MarkdownContext> {
         transform(node, config) {
           const children = node.transformChildren(config);
           const attrs = node.transformAttributes(config);
-          const href = attrs['href'].replace('docs://BASE_PATH', BASE_PATH);
+          const href = attrs['href'].replace('docs://BASE_PATH', RESOLVED_API_REFERENCE_PATH);
           return new Markdoc.Tag(this.render, { ...attrs, href }, children);
         },
       },
@@ -87,7 +87,7 @@ async function createMarkdownRenderer(): Promise<MarkdownContext> {
 
 export function DocsSearch({ settings, currentPath }: { settings: SearchSettings; currentPath: string }) {
   const markdownRenderer = React.use(createMarkdownRenderer());
-  const { stainlessPath, language } = parseRoute(BASE_PATH, currentPath);
+  const { stainlessPath, language } = parseRoute(RESOLVED_API_REFERENCE_PATH, currentPath);
   // eslint-disable-next-line turbo/no-undeclared-env-vars
   const pageFind = import.meta.env.DEV
     ? undefined
@@ -96,7 +96,7 @@ export function DocsSearch({ settings, currentPath }: { settings: SearchSettings
   function handleSelect(selectedPath: string) {
     const url = selectedPath.startsWith('/')
       ? selectedPath
-      : generateRoute(BASE_PATH, language, selectedPath);
+      : generateRoute(RESOLVED_API_REFERENCE_PATH, language, selectedPath);
     if (url) window.location.href = url;
   }
 

package/plugin/globalJs/copy.ts

@@ -1,4 +1,7 @@
-import { BASE_PATH, EXPERIMENTAL_COLLAPSIBLE_SNIPPETS } from 'virtual:stl-starlight-virtual-module';
+import {
+  RESOLVED_API_REFERENCE_PATH,
+  EXPERIMENTAL_COLLAPSIBLE_SNIPPETS,
+} from 'virtual:stl-starlight-virtual-module';
 import { getPageLoadEvent } from '../helpers/getPageLoadEvent';
 import { updateSelectedLanguage } from '../languages';
 import { navigate } from 'astro/virtual-modules/transitions-router.js';
@@ -90,7 +93,7 @@ function loadPlayground(playButton: HTMLElement) {
       container,
       onLanguageSelect: (value) => {
         const originalLanguage = document.getElementById('stldocs-snippet-select')?.dataset.currentValue;
-        const path: string = updateSelectedLanguage(BASE_PATH, originalLanguage, value);
+        const path: string = updateSelectedLanguage(RESOLVED_API_REFERENCE_PATH, originalLanguage, value);
         navigate(path.replace(/(\?.+)?($|#)/, (_, str, end) => (str ? str + '&play' : '?play') + end));
       },
       ...playgroundData,

package/plugin/globalJs/navigation.ts

@@ -1,5 +1,5 @@
 import { parseRoute, scrollToPath } from '@stainless-api/docs-ui/routing';
-import { BASE_PATH } from 'virtual:stl-starlight-virtual-module';
+import { RESOLVED_API_REFERENCE_PATH } from 'virtual:stl-starlight-virtual-module';
 import { updateSelectedLanguage } from '../languages';
 import { navigate } from 'astro:transitions/client';
 import { getPageLoadEvent } from '../helpers/getPageLoadEvent.ts';
@@ -11,7 +11,7 @@ history.scrollRestoration = 'auto';
 function getStainlessPathForLocation() {
   return document.location.hash
     ? decodeURI(document.location.hash)
-    : parseRoute(BASE_PATH, document.location.href)?.stainlessPath;
+    : parseRoute(RESOLVED_API_REFERENCE_PATH, document.location.href)?.stainlessPath;
 }
 
 window.addEventListener('popstate', (ev: PopStateEvent) => {
@@ -29,7 +29,7 @@ document.addEventListener(getPageLoadEvent(), () => {
     root: rootElement,
     onSelect: (value) => {
       const originalLanguage = rootElement?.dataset.currentValue;
-      navigate(updateSelectedLanguage(BASE_PATH, originalLanguage, value));
+      navigate(updateSelectedLanguage(RESOLVED_API_REFERENCE_PATH, originalLanguage, value));
     },
   });
 

package/plugin/index.ts

@@ -300,7 +300,7 @@ async function stlStarlightAstroIntegration(
                   if (id === resolvedId) {
                     return [
                       buildVirtualModuleString({
-                        BASE_PATH: path.posix.join(astroConfig.base, pluginConfig.basePath),
+                        RESOLVED_API_REFERENCE_PATH: path.posix.join(astroConfig.base, pluginConfig.basePath),
                         EXCLUDE_LANGUAGES: pluginConfig.excludeLanguages,
                         DEFAULT_LANGUAGE: pluginConfig.defaultLanguage,
                         BREADCRUMB_CONFIG: pluginConfig.breadcrumbs,

package/plugin/react/Routing.tsx

@@ -43,7 +43,7 @@ import {
 import { Dropdown } from '@stainless-api/docs/components';
 
 import {
-  BASE_PATH,
+  RESOLVED_API_REFERENCE_PATH,
   EXCLUDE_LANGUAGES,
   EXPAND_RESOURCES,
   HIGHLIGHT_THEMES,
@@ -282,7 +282,7 @@ export function RenderLibraries({ metadata }: { metadata: SpecMetadata }) {
           language={language}
           version={data.version || ''}
           install={data.install || ''}
-          links={{ repo: data.repo_url || '#', docs: `${BASE_PATH}/${language}` }}
+          links={{ repo: data.repo_url || '#', docs: `${RESOLVED_API_REFERENCE_PATH}/${language}` }}
         />
       ))}
     </ComponentProvider>
@@ -295,7 +295,7 @@ export function RenderSpecOverview({ spec, language }: { spec: SDKJSON.Spec; lan
   return (
     <DocsProvider spec={spec} language={language ?? 'node'}>
       <ComponentProvider components={componentOverrides}>
-        <NavigationProvider basePath={BASE_PATH}>
+        <NavigationProvider basePath={RESOLVED_API_REFERENCE_PATH}>
           <MarkdownProvider render={renderMarkdown} highlight={highlight}>
             <div className={style.Overview}>
               {resources
@@ -351,7 +351,7 @@ export function RenderSpec({
       }}
     >
       <ComponentProvider components={componentOverrides}>
-        <NavigationProvider basePath={BASE_PATH} selectedPath={path}>
+        <NavigationProvider basePath={RESOLVED_API_REFERENCE_PATH} selectedPath={path}>
           <MarkdownProvider render={renderMarkdown} highlight={highlight}>
             {
               <div className="stldocs-root stl-ui-not-prose">
@@ -359,7 +359,7 @@ export function RenderSpec({
                   <SDKBreadcrumbs
                     spec={spec as SDKJSON.Spec}
                     currentPath={currentPath}
-                    basePath={BASE_PATH}
+                    basePath={RESOLVED_API_REFERENCE_PATH}
                     config={BREADCRUMB_CONFIG}
                   />
                   {ENABLE_CONTEXT_MENU && <AIDropdown />}

package/plugin/replaceSidebarPlaceholderMiddleware.ts

@@ -1,6 +1,6 @@
 import { defineRouteMiddleware, StarlightRouteData } from '@astrojs/starlight/route-data';
 
-import { BASE_PATH } from 'virtual:stl-starlight-virtual-module';
+import { RESOLVED_API_REFERENCE_PATH } from 'virtual:stl-starlight-virtual-module';
 import { getAPIReferencePlaceholderItems } from './referencePlaceholderUtils';
 import { parseRoute } from '@stainless-api/docs-ui/routing';
 import path from 'path';
@@ -10,14 +10,17 @@ import { sidebars } from 'virtual:stl-starlight-reference-sidebars';
 
 type SidebarEntry = StarlightRouteData['sidebar'][number];
 
+const removeTrailingSlash = (value: string) => (value.endsWith('/') ? value.slice(0, -1) : value);
+
 function markCurrentItems(sidebar: SidebarEntry[], currentSlug: string) {
   // IMPORTANT: we need to clone the sidebar to avoid mutating the original sidebar
   const mutableSidebarInstance = structuredClone(sidebar);
+  const normalizedCurrentSlug = removeTrailingSlash(currentSlug);
 
   function recursiveMarkCurrent(entries: SidebarEntry[]) {
     for (const entry of entries) {
       if (entry.type === 'link') {
-        entry.isCurrent = entry.href === currentSlug;
+        entry.isCurrent = removeTrailingSlash(entry.href) === normalizedCurrentSlug;
         if (entry.isCurrent) {
           return;
         }
@@ -38,12 +41,12 @@ export const onRequest = defineRouteMiddleware(async (context) => {
   const slug = path.posix.join(import.meta.env.BASE_URL ?? '', `/${context.locals.starlightRoute.id}`); // same as .slug but not deprecated
 
   context.locals.starlightRoute._stlStarlight = {
-    basePath: BASE_PATH,
+    basePath: RESOLVED_API_REFERENCE_PATH,
   };
 
   const apiReferencePlaceholderItems = getAPIReferencePlaceholderItems(context.locals.starlightRoute.sidebar);
 
-  const { language } = parseRoute(BASE_PATH, slug);
+  const { language } = parseRoute(RESOLVED_API_REFERENCE_PATH, slug);
 
   for (const item of apiReferencePlaceholderItems) {
     const entries = sidebars.find((sb) => sb.id === item.sidebarId && sb.language === language)?.entries;

package/plugin/sidebar-utils/sidebar-builder.ts

@@ -166,10 +166,14 @@ export class SidebarConfigItemsBuilder {
     return null;
   }
 
+  private isWebhookResource(resource: SDKJSON.Resource): boolean {
+    return resource.stainlessPath === '(resource) webhooks';
+  }
+
   private toResourceOverviewPage(entry: SDKJSON.Resource): UserSidebarResourceOverviewPage {
     return {
       kind: 'resource_overview_page',
-      label: 'Overview',
+      label: this.isWebhookResource(entry) ? 'Events' : 'Overview',
       key: entry.configRef,
       badge: undefined,
       metadata: {
@@ -199,7 +203,8 @@ export class SidebarConfigItemsBuilder {
 
   private generateResourceGroup(resource: SDKJSON.Resource, collapsed: boolean): ReferenceSidebarGroup {
     const entries: ReferenceSidebarConfigItem[] = [];
-    if (!this.options?.excludeResourceOverviewPages) {
+    // even if we aren't generating resource overview pages, we want to generate them for webhooks
+    if (!this.options?.excludeResourceOverviewPages || this.isWebhookResource(resource)) {
       entries.push(this.toResourceOverviewPage(resource));
     }
     const methods = Object.values(resource.methods ?? {});

package/plugin/specs/fetchSpecSSR.ts

@@ -5,7 +5,7 @@ import { SpecWithAuth } from './generateSpec';
 
 let cachedSpecWithAuth: SpecWithAuth | null = null;
 
-export async function getSpecWithAuthInSSR() {
+async function getSpecWithAuthInSSR() {
   if (cachedSpecWithAuth) {
     return cachedSpecWithAuth;
   }

package/stl-docs/components/Head.astro

@@ -1,15 +1,15 @@
 ---
+import { Font } from 'astro:assets';
+import { FONTS } from 'virtual:stl-docs-virtual-module';
 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} />
+
+{Object.values(FONTS).map((font) => <Font cssVariable={font.cssVariable} preload={font.preload} />)}
 <link rel="alternate" type="text/markdown" href={mdPath} />
 
 <script>

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

@@ -3,26 +3,42 @@ import { SidebarEntry } from '../pagination/util';
 import { ReactNode } from 'react';
 import { Badge, getHttpMethod } from '@stainless-api/ui-primitives';
 import { FunctionIcon } from '@stainless-api/ui-primitives/icons';
+import { BracesIcon } from 'lucide-react';
+
+function getIcon(entry: SidebarEntry): ReactNode | undefined {
+  if (entry.type !== 'link') {
+    return undefined;
+  }
+  const methodAttr = entry.attrs['data-stldocs-method'];
+  const httpMethod = getHttpMethod(methodAttr);
+  if (httpMethod) {
+    return <Badge.HTTP method={httpMethod} iconOnly size="sm" />;
+  }
+
+  // special handling for the webhooks resource overview page
+  if (entry.attrs['data-stldocs-overview'] === 'webhooks') {
+    return (
+      <Badge size="sm" icon={<BracesIcon />} intent="info">
+        {''}
+      </Badge>
+    );
+  }
+
+  // Support empty string as method to show generic "Function" badge
+  else if (methodAttr === '') {
+    return (
+      <Badge size="sm" icon={<FunctionIcon />} intent="info">
+        {''}
+      </Badge>
+    );
+  }
+  return undefined;
+}
 
 export function convertAstroSidebarToStl(entries: SidebarEntry[]): StlSidebarEntry[] {
   return entries.map((entry): StlSidebarEntry => {
     if (entry.type === 'link') {
-      let icon: ReactNode | undefined;
-
-      const methodAttr = entry.attrs['data-stldocs-method'];
-      const httpMethod = getHttpMethod(methodAttr);
-      if (httpMethod) {
-        icon = <Badge.HTTP method={httpMethod} iconOnly size="sm" />;
-      }
-      // Support empty string as method to show generic "Function" badge
-      else if (methodAttr === '') {
-        icon = (
-          <Badge size="sm" icon={<FunctionIcon />} intent="info">
-            {''}
-          </Badge>
-        );
-      }
-
+      const icon = getIcon(entry);
       return {
         type: 'link',
         attrs: entry.attrs,

package/stl-docs/fonts.ts

@@ -0,0 +1,172 @@
+import type { AstroConfig } from 'astro';
+import type { Defined } from './loadStlDocsConfig';
+import { fontProviders } from 'astro/config';
+import type { FontPreloadFilter } from 'astro:assets';
+
+type AstroFontConfigEntry = Defined<AstroConfig['experimental']['fonts']>[number];
+
+// Apply Omit to each member of the union while preserving union structure
+export type StlDocsFontConfigEntry = (AstroFontConfigEntry extends infer T
+  ? T extends unknown
+    ? Omit<T, 'cssVariable'>
+    : never
+  : never) & { preload?: FontPreloadFilter };
+
+export type StlDocsFontConfig = {
+  primary?: StlDocsFontConfigEntry;
+  heading?: StlDocsFontConfigEntry;
+  mono?: StlDocsFontConfigEntry;
+};
+const latinFeatureSettings = "'ss01' on, 'ss03' on, 'ss04' on, 'ss06' on, 'ss08' on";
+/* prettier-ignore */
+const latinUnicodeRange: readonly string[] = ['U+0000-00FF', 'U+0131', 'U+0152-0153', 'U+02BB-02BC', 'U+02C6', 'U+02DA', 'U+02DC', 'U+0304', 'U+0308', 'U+0329', 'U+2000-206F', 'U+20AC', 'U+2122', 'U+2191', 'U+2193', 'U+2212', 'U+2215', 'U+FEFF', 'U+FFFD'];
+// /* prettier-ignore */
+// const latinExtUnicodeRange: readonly string[] = ['U+0100-02BA', 'U+02BD-02C5', 'U+02C7-02CC', 'U+02CE-02D7', 'U+02DD-02FF', 'U+0304', 'U+0308', 'U+0329', 'U+1D00-1DBF', 'U+1E00-1E9F', 'U+1EF2-1EFF', 'U+2020', 'U+20A0-20AB', 'U+20AD-20C0', 'U+2113', 'U+2C60-2C7F', 'U+A720-A7FF'];
+
+export function getFontRoles(fonts: StlDocsFontConfig | undefined) {
+  if (!fonts) {
+    return {};
+  }
+  const fontConfigs: {
+    primary?: { cssVariable: string; preload?: FontPreloadFilter };
+    heading?: { cssVariable: string; preload?: FontPreloadFilter };
+    mono?: { cssVariable: string; preload?: FontPreloadFilter };
+  } = {};
+  if (fonts.primary) {
+    fontConfigs['primary'] = {
+      cssVariable: '--stl-typography-font' as const,
+      preload: fonts.primary.preload ?? [{ style: 'normal' }],
+    };
+  }
+  if (fonts.heading) {
+    fontConfigs['heading'] = {
+      cssVariable: '--stl-typography-font-heading' as const,
+      preload: fonts.heading.preload ?? [{ style: 'normal' }],
+    };
+  }
+  if (fonts.mono) {
+    fontConfigs['mono'] = {
+      cssVariable: '--stl-typography-font-mono' as const,
+      preload: fonts.mono.preload ?? [{ style: 'normal' }],
+    };
+  }
+  return fontConfigs;
+}
+
+export function normalizeFonts(fonts: StlDocsFontConfig | undefined): StlDocsFontConfig {
+  const defaultPrimary: StlDocsFontConfigEntry = {
+    provider: fontProviders.local(),
+    name: 'Geist',
+    display: 'swap',
+    preload: [
+      {
+        weight: '100 900',
+        style: 'normal',
+      },
+    ],
+    options: {
+      variants: [
+        {
+          weight: '100 900',
+          style: 'normal',
+          src: [new URL('../assets/fonts/geist/geist-latin.woff2', import.meta.url)],
+          unicodeRange: latinUnicodeRange,
+          featureSettings: latinFeatureSettings,
+        },
+        {
+          weight: '100 900',
+          style: 'italic',
+          src: [new URL('../assets/fonts/geist/geist-italic-latin.woff2', import.meta.url)],
+          unicodeRange: latinUnicodeRange,
+          featureSettings: latinFeatureSettings,
+        },
+        // {
+        //   weight: '100 900',
+        //   style: 'normal',
+        //   src: [new URL('../assets/fonts/geist/geist-latin-ext.woff2', import.meta.url)],
+        //   unicodeRange: latinExtUnicodeRange,
+        //   featureSettings: latinFeatureSettings,
+        // },
+        // {
+        //   weight: '100 900',
+        //   style: 'italic',
+        //   src: [new URL('../assets/fonts/geist/geist-italic-latin-ext.woff2', import.meta.url)],
+        //   unicodeRange: latinExtUnicodeRange,
+        //   featureSettings: latinFeatureSettings,
+        // },
+      ],
+    },
+  };
+  const defaultMono: StlDocsFontConfigEntry = {
+    provider: fontProviders.local(),
+    name: 'Geist Mono',
+    display: 'swap',
+    preload: [
+      {
+        weight: '100 900',
+        style: 'normal',
+      },
+    ],
+    options: {
+      variants: [
+        {
+          weight: '100 900',
+          style: 'normal',
+          src: [new URL('../assets/fonts/geist/geist-mono-latin.woff2', import.meta.url)],
+          unicodeRange: latinUnicodeRange,
+        },
+        {
+          weight: '100 900',
+          style: 'italic',
+          src: [new URL('../assets/fonts/geist/geist-mono-italic-latin.woff2', import.meta.url)],
+          unicodeRange: latinUnicodeRange,
+        },
+        // {
+        //   weight: '100 900',
+        //   style: 'normal',
+        //   src: [new URL('../assets/fonts/geist/geist-mono-latin-ext.woff2', import.meta.url)],
+        //   unicodeRange: latinExtUnicodeRange,
+        // },
+        // {
+        //   weight: '100 900',
+        //   style: 'italic',
+        //   src: [new URL('../assets/fonts/geist/geist-mono-italic-latin-ext.woff2', import.meta.url)],
+        //   unicodeRange: latinExtUnicodeRange,
+        // },
+      ],
+    },
+  };
+
+  return {
+    primary: fonts?.primary ?? defaultPrimary,
+    heading: fonts?.heading ?? undefined,
+    mono: fonts?.mono ?? defaultMono,
+  };
+}
+
+// Normalize fonts for the Astro config
+export function flattenFonts(fonts: StlDocsFontConfig | undefined): AstroFontConfigEntry[] {
+  if (!fonts) {
+    return [];
+  }
+  const fontConfigs: AstroFontConfigEntry[] = [];
+  if (fonts.primary) {
+    fontConfigs.push({
+      ...fonts.primary,
+      cssVariable: '--stl-typography-font' as const,
+    } as AstroFontConfigEntry);
+  }
+  if (fonts.heading) {
+    fontConfigs.push({
+      ...fonts.heading,
+      cssVariable: '--stl-typography-font-heading' as const,
+    } as AstroFontConfigEntry);
+  }
+  if (fonts.mono) {
+    fontConfigs.push({
+      ...fonts.mono,
+      cssVariable: '--stl-typography-font-mono' as const,
+    } as AstroFontConfigEntry);
+  }
+  return fontConfigs;
+}

package/stl-docs/index.ts

@@ -6,7 +6,7 @@ import { disableCalloutSyntaxStarlightPlugin } from './disableCalloutSyntax';
 import type { AstroIntegration } from 'astro';
 
 import { normalizeRedirects, type NormalizedRedirectConfig } from './redirects';
-import path, { join } from 'path';
+import { join } from 'path';
 import { mkdirSync, writeFileSync } from 'fs';
 import {
   parseStlDocsConfig,
@@ -23,6 +23,7 @@ import { stainlessDocsMarkdownRenderer } from './proseMarkdown/proseMarkdownInte
 import { setSharedLogger } from '../shared/getSharedLogger';
 import { stainlessDocsAlgoliaProseIndexing, stainlessDocsVectorProseIndexing } from './proseSearchIndexing';
 import { stainlessStarlight } from '../plugin';
+import { getFontRoles, flattenFonts } from './fonts';
 
 export * from '../plugin';
 
@@ -167,8 +168,6 @@ function stainlessDocsIntegration(
           redirects = normalizeRedirects(astroConfig.redirects);
         }
 
-        const fullApiReferenceBasePath = path.posix.join(astroConfig.base, apiReferenceBasePath ?? '/api');
-
         const virtualModules = new Map(
           Object.entries({
             'virtual:stl-docs-virtual-module': buildVirtualModuleString({
@@ -177,10 +176,11 @@ function stainlessDocsIntegration(
               HEADER_LINKS: config.header.links,
               HEADER_LAYOUT: config.header.layout,
               ENABLE_CLIENT_ROUTER: config.enableClientRouter,
-              API_REFERENCE_BASE_PATH: fullApiReferenceBasePath,
+              API_REFERENCE_BASE_PATH: apiReferenceBasePath ?? '/api',
               ENABLE_PROSE_MARKDOWN_RENDERING: config.enableProseMarkdownRendering,
               ENABLE_CONTEXT_MENU: config.contextMenu, // TODO: do not duplicate this between both virtual modules
               RENDER_PAGE_DESCRIPTIONS: config.renderPageDescriptions,
+              FONTS: getFontRoles(config.fonts),
             } satisfies typeof StlDocsVirtualModule),
 
             'virtual:stl-docs/components/AiChat.tsx': `
@@ -196,6 +196,9 @@ function stainlessDocsIntegration(
         );
 
         updateConfig({
+          experimental: {
+            fonts: flattenFonts(config.fonts),
+          },
           vite: {
             plugins: [
               {

package/stl-docs/loadStlDocsConfig.ts

@@ -3,6 +3,7 @@ import type { StarlightPlugin, StarlightUserConfig } from '@astrojs/starlight/ty
 import type { ButtonVariant } from '@stainless-api/ui-primitives';
 import type { AnchorHTMLAttributes } from 'react';
 import type starlight from '@astrojs/starlight';
+import { normalizeFonts, type StlDocsFontConfig } from './fonts';
 
 type StarlightConfig = Parameters<typeof starlight>[0];
 
@@ -66,6 +67,7 @@ export type StainlessDocsUserConfig = {
     layout?: HeaderLayout;
     links?: HeaderLink[];
   };
+  fonts?: StlDocsFontConfig;
   experimental?: {
     starlightCompat?: ExperimentalStarlightCompatibilityConfig;
     enableClientRouter?: boolean;
@@ -139,6 +141,7 @@ function normalizeConfig(userConfig: StainlessDocsUserConfig) {
       layout: userConfig.header?.layout ?? 'default',
       links: userConfig.header?.links ?? [],
     },
+    fonts: normalizeFonts(userConfig.fonts),
     starlightPassThrough: {
       tableOfContents: userConfig.tableOfContents,
       titleDelimiter: userConfig.titleDelimiter,

package/stl-docs/proseMarkdown/proseMarkdownMiddleware.ts

@@ -1,6 +1,7 @@
 import { defineMiddleware } from 'astro:middleware';
 import { toMarkdown } from './toMarkdown';
 import { API_REFERENCE_BASE_PATH } from 'virtual:stl-docs-virtual-module';
+import path from 'path';
 
 // this is only run in `astro dev` for rendering prose content as Markdown on the fly.
 export const onRequest = defineMiddleware(async (context, next) => {
@@ -9,7 +10,8 @@ export const onRequest = defineMiddleware(async (context, next) => {
     return next();
   }
 
-  if (API_REFERENCE_BASE_PATH && context.url.pathname.startsWith(API_REFERENCE_BASE_PATH)) {
+  const resolvedBasePath = path.posix.join(import.meta.env.BASE_URL ?? '', API_REFERENCE_BASE_PATH);
+  if (resolvedBasePath && context.url.pathname.startsWith(resolvedBasePath)) {
     // handled by the API reference API route in stl-starlight plugin
     return next();
   }

package/theme.css

@@ -1,7 +1,6 @@
 @layer starlight.base, starlight.reset, starlight.core, starlight.content, starlight.components, starlight.utils;
 @layer starlight;
 
-@import './styles/fonts.css';
 @import './styles/links.css';
 @import './styles/sidebar.css';
 @import './styles/search.css';

package/virtual-module.d.ts

@@ -4,7 +4,7 @@ declare module 'virtual:stl-starlight-virtual-module' {
   import type { StlStarlightMiddleware } from '@stainless-api/docs/plugin/MiddlewareTypes';
   import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
 
-  export const BASE_PATH: string;
+  export const RESOLVED_API_REFERENCE_PATH: string;
   export const EXCLUDE_LANGUAGES: DocsLanguage[];
   export const DEFAULT_LANGUAGE: string;
   export const BREADCRUMB_CONFIG: {
@@ -26,6 +26,7 @@ declare module 'virtual:stl-starlight-virtual-module' {
 declare module 'virtual:stl-docs-virtual-module' {
   import type { ButtonVariant } from '@stainless-api/ui-primitives';
   import type { AnchorHTMLAttributes } from 'react';
+  import { FontPreloadFilter } from 'astro:assets';
 
   type Tab = {
     label: string;
@@ -33,6 +34,11 @@ declare module 'virtual:stl-docs-virtual-module' {
     hidden?: boolean;
   };
 
+  type FontConfig = {
+    cssVariable: string;
+    preload?: FontPreloadFilter;
+  };
+
   export const HEADER_LINKS: {
     label: string;
     link: string;
@@ -43,10 +49,15 @@ declare module 'virtual:stl-docs-virtual-module' {
   export const SPLIT_TABS_ENABLED: boolean;
   export const HEADER_LAYOUT: 'default' | 'stacked';
   export const ENABLE_CLIENT_ROUTER: boolean;
-  export const API_REFERENCE_BASE_PATH: string | null;
+  export const API_REFERENCE_BASE_PATH: string;
   export const ENABLE_PROSE_MARKDOWN_RENDERING: boolean;
   export const ENABLE_CONTEXT_MENU: boolean;
   export const RENDER_PAGE_DESCRIPTIONS: boolean;
+  export const FONTS: {
+    primary?: FontConfig;
+    heading?: FontConfig;
+    mono?: FontConfig;
+  };
 }
 
 declare module 'virtual:stl-docs/components/AiChat.tsx' {

package/styles/fonts.css

@@ -1,83 +0,0 @@
-/* Geist */
-@font-face {
-  font-family: 'Geist';
-  font-style: normal;
-  font-display: swap;
-  font-weight: 100 900;
-  src: url(../assets/fonts/geist/geist-latin.woff2) format('woff2-variations');
-  unicode-range:
-    U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329,
-    U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
-}
-@font-face {
-  font-family: 'Geist';
-  font-style: italic;
-  font-display: swap;
-  font-weight: 100 900;
-  src: url(../assets/fonts/geist/geist-italic-latin.woff2) format('woff2-variations');
-  unicode-range:
-    U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329,
-    U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
-}
-@font-face {
-  font-family: 'Geist';
-  font-style: normal;
-  font-display: swap;
-  font-weight: 100 900;
-  src: url(../assets/fonts/geist/geist-latin-ext.woff2) format('woff2-variations');
-  unicode-range:
-    U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF,
-    U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
-}
-@font-face {
-  font-family: 'Geist';
-  font-style: italic;
-  font-display: swap;
-  font-weight: 100 900;
-  src: url(../assets/fonts/geist/geist-italic-latin-ext.woff2) format('woff2-variations');
-  unicode-range:
-    U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF,
-    U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
-}
-
-/* Geist Mono */
-@font-face {
-  font-family: 'Geist Mono';
-  font-style: normal;
-  font-display: swap;
-  font-weight: 100 900;
-  src: url(../assets/fonts/geist/geist-mono-latin.woff2) format('woff2-variations');
-  unicode-range:
-    U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329,
-    U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
-}
-@font-face {
-  font-family: 'Geist Mono';
-  font-style: italic;
-  font-display: swap;
-  font-weight: 100 900;
-  src: url(../assets/fonts/geist/geist-mono-italic-latin.woff2) format('woff2-variations');
-  unicode-range:
-    U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329,
-    U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
-}
-@font-face {
-  font-family: 'Geist Mono';
-  font-style: normal;
-  font-display: swap;
-  font-weight: 100 900;
-  src: url(../assets/fonts/geist/geist-mono-latin-ext.woff2) format('woff2-variations');
-  unicode-range:
-    U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF,
-    U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
-}
-@font-face {
-  font-family: 'Geist Mono';
-  font-style: italic;
-  font-display: swap;
-  font-weight: 100 900;
-  src: url(../assets/fonts/geist/geist-mono-italic-latin-ext.woff2) format('woff2-variations');
-  unicode-range:
-    U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF,
-    U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
-}