@stainless-api/docs 0.1.0-beta.60 → 0.1.0-beta.62

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @stainless-api/docs
 
+## 0.1.0-beta.62
+
+### Patch Changes
+
+- 3c4a030: increase minimum starlight depdendency version
+- cd86726: Fix a crash when stl-starlight plugin isn’t being loaded
+- aa9d333: fixes for markdown rendering when astro integrations override the starlight html entrypoint
+- 07a2c87: Should override ThemeProvider for setting theme within the html head
+  - @stainless-api/docs-search@0.1.0-beta.3
+  - @stainless-api/docs-ui@0.1.0-beta.51
+  - @stainless-api/ui-primitives@0.1.0-beta.38
+
+## 0.1.0-beta.61
+
+### Patch Changes
+
+- 88a9894: patch vite optimizeDeps for docs-ai-chat
+- Updated dependencies [2a79bae]
+  - @stainless-api/ui-primitives@0.1.0-beta.38
+  - @stainless-api/docs-ui@0.1.0-beta.51
+  - @stainless-api/docs-search@0.1.0-beta.3
+
 ## 0.1.0-beta.60
 
 ### Patch Changes

package/locals.d.ts

@@ -11,6 +11,7 @@ declare namespace App {
       fullSidebar?: SidebarEntry[];
     };
 
+    stainlessProject?: string;
     language?: import('@stainless-api/docs-ui/routing').DocsLanguage;
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.60",
+  "version": "0.1.0-beta.62",
   "publishConfig": {
     "access": "public"
   },
@@ -25,7 +25,7 @@
     "node": ">=18.17.1"
   },
   "peerDependencies": {
-    "@astrojs/starlight": ">=0.36.1",
+    "@astrojs/starlight": ">=0.37.0",
     "astro": ">=5.15.3",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
@@ -52,9 +52,9 @@
     "vite-plugin-prebundle-workers": "^0.2.0",
     "web-worker": "^1.5.0",
     "yaml": "^2.8.2",
-    "@stainless-api/docs-ui": "0.1.0-beta.50",
-    "@stainless-api/docs-search": "0.1.0-beta.2",
-    "@stainless-api/ui-primitives": "0.1.0-beta.37"
+    "@stainless-api/docs-ui": "0.1.0-beta.51",
+    "@stainless-api/docs-search": "0.1.0-beta.3",
+    "@stainless-api/ui-primitives": "0.1.0-beta.38"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.6",
@@ -68,7 +68,7 @@
     "typescript": "5.9.3",
     "vite": "^6.4.1",
     "zod": "^4.1.13",
-    "@stainless/eslint-config": "0.1.0-beta.0",
+    "@stainless/eslint-config": "0.1.0-beta.1",
     "@stainless/sdk-json": "^0.1.0-beta.2"
   },
   "scripts": {

package/plugin/index.ts

@@ -301,7 +301,6 @@ async function stlStarlightAstroIntegration(
                         PROPERTY_SETTINGS: pluginConfig.propertySettings,
                         ENABLE_CONTEXT_MENU: pluginConfig.contextMenu,
                         EXPERIMENTAL_PLAYGROUNDS: !!pluginConfig.experimentalPlaygrounds,
-                        STAINLESS_PROJECT: version.stainlessProject,
                       } satisfies Omit<typeof StlStarlightVirtualModule, 'MIDDLEWARE'>),
                       vmMiddlewareExport,
                     ].join('\n');

package/stl-docs/components/AiChatIsland.tsx

@@ -1,10 +1,8 @@
 import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
-import AiChat from 'virtual:stl-docs/components/AiChat.tsx';
-// right now loading AiChat without API reference plugin is unsupported
-// because the AiChat is for talking about the SDKs
-import { STAINLESS_PROJECT } from 'virtual:stl-starlight-virtual-module';
+import AiChat, { STAINLESS_PROJECT } from 'virtual:stl-docs/components/AiChat.tsx';
 
 export default function AiChatIsland({ currentLanguage }: { currentLanguage: DocsLanguage | undefined }) {
   if (!AiChat) throw new Error('AiChatIsland was rendered but could not load AiChat component');
+  if (!STAINLESS_PROJECT) return null;
   return <AiChat projectId={STAINLESS_PROJECT} language={currentLanguage} />;
 }

package/stl-docs/components/ThemeProvider.astro

@@ -0,0 +1,36 @@
+{/* Inlined to avoid FOUC. All theme selects are initialized here */}
+<script is:inline>
+  window.didInitThemePickers = window.didInitThemePickers ?? false;
+
+  // Only run once.
+  if (!window.didInitThemePickers) {
+    window.didInitThemePickers = true;
+
+    // The stored theme will be either 'auto', 'light', 'dark' or null.
+    const storedTheme = typeof localStorage !== 'undefined' && localStorage.getItem('starlight-theme');
+
+    // This theme is either 'light' or 'dark'. It's used for setting the data-theme attribute.
+    const theme =
+      !storedTheme || storedTheme === 'auto'
+        ? window.matchMedia('(prefers-color-scheme: light)').matches
+          ? 'light'
+          : 'dark'
+        : storedTheme;
+
+    document.documentElement.dataset.theme = theme === 'light' ? 'light' : 'dark';
+
+    const themeSelects = document.querySelectorAll('[data-theme-select]');
+    const selectedThemeValue = storedTheme || 'auto';
+
+    themeSelects.forEach((select) => {
+      const tmpl = select.querySelector(`[data-value="${selectedThemeValue}"] template`);
+      const selectedSlot = select.querySelector('[data-part="trigger-selected"]');
+
+      selectedSlot.innerHTML = '';
+      if (tmpl) {
+        selectedSlot.appendChild(tmpl.content.cloneNode(true));
+        return;
+      }
+    });
+  }
+</script>

package/stl-docs/components/ThemeSelect.astro

@@ -88,43 +88,6 @@ const options = [
   </Dropdown.Menu>
 </Dropdown>
 
-{/* Inlined to avoid FOUC. All theme selects are initialized here */}
-<script is:inline>
-  window.didInitThemePickers = window.didInitThemePickers ?? false;
-
-  // Only run once.
-  if (!window.didInitThemePickers) {
-    window.didInitThemePickers = true;
-
-    // The stored theme will be either 'auto', 'light', 'dark' or null.
-    const storedTheme = typeof localStorage !== 'undefined' && localStorage.getItem('starlight-theme');
-
-    // This theme is either 'light' or 'dark'. It's used for setting the data-theme attribute.
-    const theme =
-      !storedTheme || storedTheme === 'auto'
-        ? window.matchMedia('(prefers-color-scheme: light)').matches
-          ? 'light'
-          : 'dark'
-        : storedTheme;
-
-    document.documentElement.dataset.theme = theme === 'light' ? 'light' : 'dark';
-
-    const themeSelects = document.querySelectorAll('[data-theme-select]');
-    const selectedThemeValue = storedTheme || 'auto';
-
-    themeSelects.forEach((select) => {
-      const tmpl = select.querySelector(`[data-value="${selectedThemeValue}"] template`);
-      const selectedSlot = select.querySelector('[data-part="trigger-selected"]');
-
-      selectedSlot.innerHTML = '';
-      if (tmpl) {
-        selectedSlot.appendChild(tmpl.content.cloneNode(true));
-        return;
-      }
-    });
-  }
-</script>
-
 <script>
   import { getPageLoadEvent } from '../../plugin/helpers/getPageLoadEvent';
   import { initDropdown } from '@stainless-api/docs/components/scripts';

package/stl-docs/index.ts

@@ -52,6 +52,7 @@ function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig
 
     Head: resolveSrcFile(COMPONENTS_FOLDER, './Head.astro'),
     Header: resolveSrcFile(COMPONENTS_FOLDER, './Header.astro'),
+    ThemeProvider: resolveSrcFile(COMPONENTS_FOLDER, './ThemeProvider.astro'),
     ThemeSelect: resolveSrcFile(COMPONENTS_FOLDER, './ThemeSelect.astro'),
 
     Sidebar: resolveSrcFile(COMPONENTS_FOLDER, './sidebars/BaseSidebar.astro'),
@@ -158,15 +159,19 @@ function stainlessDocsIntegration(
         ENABLE_CLIENT_ROUTER: config.enableClientRouter,
         API_REFERENCE_BASE_PATH: apiReferenceBasePath,
         ENABLE_PROSE_MARKDOWN_RENDERING: config.enableProseMarkdownRendering,
-        // TODO: do not duplicate this between both virtual modules
-        ENABLE_CONTEXT_MENU: config.contextMenu,
+        ENABLE_CONTEXT_MENU: config.contextMenu, // TODO: do not duplicate this between both virtual modules
         RENDER_PAGE_DESCRIPTIONS: config.renderPageDescriptions,
       } satisfies typeof StlDocsVirtualModule),
 
-      'virtual:stl-docs/components/AiChat.tsx': config.aiChat
-        ? `export { default } from ${JSON.stringify(config.aiChat.chatComponentPath)};`
-        : // export null when no AI chat component is provided
-          `export default null;`,
+      'virtual:stl-docs/components/AiChat.tsx': `
+        ${
+          config.aiChat
+            ? `export { default } from ${JSON.stringify(config.aiChat.chatComponentPath)};`
+            : // export null when no AI chat component is provided
+              `export default null;`
+        }
+        export const STAINLESS_PROJECT = ${config.apiReference ? JSON.stringify(config.apiReference.stainlessProject) : 'undefined'};
+      `,
     }),
   );
 
@@ -198,6 +203,15 @@ function stainlessDocsIntegration(
                 },
               },
             ],
+            optimizeDeps: {
+              include: config.aiChat
+                ? [
+                    '@stainless-api/docs-ai-chat > motion',
+                    '@stainless-api/docs-ai-chat > react-markdown',
+                    '@stainless-api/docs-ai-chat > react-syntax-highlighter',
+                  ]
+                : [],
+            },
           },
           build: {
             ...astroConfig.build,
@@ -253,7 +267,10 @@ export function stainlessDocs(config: StainlessDocsUserConfig) {
     react(),
     stainlessDocsStarlightIntegration(normalizedConfig),
     stainlessDocsIntegration(normalizedConfig, apiReferenceBasePath),
-    stainlessDocsMarkdownRenderer({ enabled: normalizedConfig.enableProseMarkdownRendering }),
+    stainlessDocsMarkdownRenderer({
+      enabled: normalizedConfig.enableProseMarkdownRendering,
+      apiReferenceBasePath,
+    }),
     stainlessDocsProseIndexing(),
   ];
 }

package/stl-docs/proseMarkdown/proseMarkdownIntegration.ts

@@ -1,11 +1,18 @@
 import type { AstroIntegration } from 'astro';
-import { readFile, writeFile } from 'fs/promises';
+import { readdir, readFile, writeFile } from 'fs/promises';
 import { toMarkdown } from './toMarkdown';
 import { resolveSrcFile } from '../../resolveSrcFile';
 import { getSharedLogger } from '../../shared/getSharedLogger';
+import { join, relative } from 'path';
 import { bold } from '../../shared/terminalUtils';
 
-export function stainlessDocsMarkdownRenderer({ enabled }: { enabled: boolean }): AstroIntegration {
+export function stainlessDocsMarkdownRenderer({
+  enabled,
+  apiReferenceBasePath,
+}: {
+  enabled: boolean;
+  apiReferenceBasePath: string | null;
+}): AstroIntegration {
   return {
     name: 'stl-docs-md',
     hooks: {
@@ -17,29 +24,44 @@ export function stainlessDocsMarkdownRenderer({ enabled }: { enabled: boolean })
           });
         }
       },
-      'astro:build:done': async ({ assets, logger: localLogger, dir }) => {
+      'astro:build:done': async ({ logger: localLogger, dir }) => {
         const logger = getSharedLogger({ fallback: localLogger });
         if (!enabled) {
           logger.info('Stainless Docs prose Markdown rendering is disabled, skipping...');
           return;
         }
-        const starlightPagePatterns = ['/[...slug]'];
-        const pagesToRender = Array.from(assets.entries())
-          .filter(([k]) => {
-            if (starlightPagePatterns.includes(k)) {
-              return true;
-            }
-            return false;
-          })
-          .map(([, v]) => v)
-          .flat()
-          .map((v) => v.pathname);
+        const outputBasePath = dir.pathname;
 
-        logger.info(bold(`Building ${pagesToRender.length} Markdown pages for prose content`));
+        // Read all HTML files from output directory, and not from assets.
+        // We cannot use the `assets` map here because it is not guaranteed to
+        // contain all files, especially if they were generated by other integrations.
+        // Other astro integrations may hijack the "[...slug]" entrypoint, and any files
+        // previously in the [...slug] asset map entry would be lost (this is where starlight stores
+        // its prose HTML files).
+        const allFiles = await readdir(outputBasePath, {
+          recursive: true,
+          withFileTypes: true,
+        });
 
-        const outputBasePath = dir.pathname;
+        const htmlFiles = allFiles
+          .filter((file) => file.isFile() && file.name.endsWith('.html'))
+          .map((file) => join(file.parentPath, file.name));
+
+        // Filter out API reference pages
+        const pagesToRender = htmlFiles.filter((absPath) => {
+          if (!apiReferenceBasePath) {
+            return true;
+          }
+          const relPath = relative(outputBasePath, absPath);
+          // Normalize by removing leading/trailing slashes from apiReferenceBasePath
+          const normalizedApiPath = apiReferenceBasePath.replace(/^\/+|\/+$/g, '');
+          return !relPath.startsWith(normalizedApiPath);
+        });
+
+        logger.info(bold(`Building ${pagesToRender.length} Markdown pages for prose content`));
 
         let completedCount = 0;
+
         for (const absHtmlPath of pagesToRender) {
           const txt = await readFile(absHtmlPath, 'utf-8');
           const md = await toMarkdown(txt);

package/stl-docs/proseMarkdown/proseMarkdownMiddleware.ts

@@ -18,7 +18,12 @@ export const onRequest = defineMiddleware(async (context, next) => {
     return next();
   }
 
-  const htmlUrl = new URL(context.url.pathname.replace('index.md', ''), context.url);
+  const pathname = context.url.pathname.replace('index.md', '');
+
+  // We must trim the trailing slash to support astro configs with `trailingSlash: 'never'`
+  const cleanPathname = pathname !== '/' ? pathname.replace(/\/$/, '') : pathname;
+  const htmlUrl = new URL(cleanPathname, context.url);
+
   const resp = await fetch(htmlUrl);
   if (!resp.ok) {
     return new Response('Failed to fetch HTML', { status: 400 });

package/virtual-module.d.ts

@@ -23,7 +23,6 @@ declare module 'virtual:stl-starlight-virtual-module' {
   export const PROPERTY_SETTINGS: PropertySettingsType;
   export const MIDDLEWARE: StlStarlightMiddleware;
   export const ENABLE_CONTEXT_MENU: boolean;
-  export const STAINLESS_PROJECT: string;
 }
 
 declare module 'virtual:stl-docs-virtual-module' {
@@ -60,4 +59,5 @@ declare module 'virtual:stl-docs/components/AiChat.tsx' {
       }>
     | null;
   export default AiChatComponent;
+  export const STAINLESS_PROJECT: string | undefined;
 }