@stainless-api/docs 0.1.0-beta.125 → 0.1.0-beta.127

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @stainless-api/docs
 
+## 0.1.0-beta.127
+
+### Patch Changes
+
+- e0d595f: Fix snippet copy button click handler
+- 8752b4e: Fix getProsePages treating all pages as prose when API reference basePath is ""
+- Updated dependencies [871f3c0]
+- Updated dependencies [871f3c0]
+  - @stainless-api/docs-ui@0.1.0-beta.91
+  - @stainless-api/docs-search@0.1.0-beta.44
+
+## 0.1.0-beta.126
+
+### Patch Changes
+
+- 992a07a: Update vendored preview worker
+- 1d1fa35: Use astro remark instead of `marked` to process api reference markdown
+- Updated dependencies [374c0e4]
+  - @stainless-api/ui-primitives@0.1.0-beta.51
+  - @stainless-api/docs-ui@0.1.0-beta.90
+  - @stainless-api/docs-search@0.1.0-beta.43
+
 ## 0.1.0-beta.125
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.125",
+  "version": "0.1.0-beta.127",
   "publishConfig": {
     "access": "public"
   },
@@ -41,15 +41,15 @@
     "vite": ">=7.3.1"
   },
   "dependencies": {
-    "@astrojs/markdown-remark": "^7.0.1",
-    "@astrojs/react": "^5.0.1",
+    "@astrojs/markdown-remark": "^7.1.0",
+    "@astrojs/react": "^5.0.2",
+    "@markdoc/markdoc": "^0.5.7",
     "@stainless-api/sdk": "0.5.0",
     "astro-expressive-code": "^0.41.7",
     "cheerio": "^1.2.0",
     "clsx": "^2.1.1",
-    "dotenv": "17.3.1",
+    "dotenv": "17.4.0",
     "lucide-react": "^0.577.0",
-    "marked": "^17.0.5",
     "node-html-parser": "^7.1.0",
     "rehype-parse": "^9.0.1",
     "rehype-remark": "^10.0.1",
@@ -61,20 +61,19 @@
     "vite-plugin-prebundle-workers": "^0.2.0",
     "web-worker": "^1.5.0",
     "yaml": "^2.8.3",
-    "@stainless-api/docs-search": "0.1.0-beta.42",
-    "@stainless-api/docs-ui": "0.1.0-beta.89",
-    "@stainless-api/ui-primitives": "0.1.0-beta.50"
+    "@stainless-api/docs-search": "0.1.0-beta.44",
+    "@stainless-api/docs-ui": "0.1.0-beta.91",
+    "@stainless-api/ui-primitives": "0.1.0-beta.51"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.8",
-    "@markdoc/markdoc": "^0.5.6",
     "@types/node": "24.12.0",
     "@types/react": "19.2.14",
     "@types/react-dom": "^19.2.3",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "tsx": "^4.21.0",
-    "typescript": "5.9.3",
+    "typescript": "6.0.2",
     "vite": "^7.3.1",
     "vitest": "^4.1.2",
     "zod": "^4.3.6",

package/plugin/components/RequestBuilder/index.tsx

@@ -22,7 +22,7 @@ export function RequestBuilder({
     if (!spec) throw new Error('Spec is required for RequestBuilder');
     params = spec && extractParams(spec, method);
   } catch (e) {
-    console.warn(e); // eslint-disable-line @eslint-react/purity
+    console.warn(e);
     return <div className={className}>{children}</div>;
   }
   /* eslint-enable */

package/plugin/globalJs/copy.ts

@@ -33,7 +33,7 @@ const preloadPlayground = (event: Event) => {
 };
 addEventListener('mouseover', preloadPlayground);
 addEventListener('click', (event) => {
-  if (!(event.target instanceof HTMLElement)) return;
+  if (!(event.target instanceof Element)) return;
   const copyButton = event.target.closest('[data-stldocs-snippet-copy]');
   if (!(copyButton instanceof HTMLElement)) return;
 

package/plugin/globalJs/navigation.ts

@@ -39,24 +39,22 @@ document.addEventListener(getPageLoadEvent(), () => {
 });
 
 document.addEventListener('click', (event) => {
-  const toggle = (event.target as HTMLElement).closest(
-    '[data-stldocs-property-toggle-expanded] > .stldocs-expand-toggle-content',
-  )?.parentElement;
+  const toggle =
+    event.target instanceof HTMLElement && event.target.closest('[data-stldocs-property-toggle-expanded]');
+  if (!toggle || !(toggle instanceof HTMLElement)) return;
 
-  if (!toggle) return;
-
-  const state = toggle.dataset.stldocsPropertyToggleExpanded === 'true';
-  toggle.dataset.stldocsPropertyToggleExpanded = state ? 'false' : 'true';
+  // Toggle the “expanded” state of the toggle
+  const toggleIsExpanded = toggle.dataset.stldocsPropertyToggleExpanded === 'true';
+  toggle.dataset.stldocsPropertyToggleExpanded = (!toggleIsExpanded).toString();
 
+  // Find the described “property group”
   const targetGroup = toggle.dataset.stldocsPropertyToggleTarget;
   if (!targetGroup) return;
-
   const target = document.querySelector(`[data-stldocs-property-group=${targetGroup}]`);
   if (!target) return;
 
-  target.querySelectorAll('details').forEach((details) => {
-    const el = details;
-    const initial = el.dataset.stldocsExpanderInitialState;
-    el.open = initial === 'true' ? true : !state;
+  // Expand or collapse all <details> elements within the target group
+  [...target.getElementsByTagName('details')].forEach((el) => {
+    el.open = el.dataset.stldocsExpanderInitialState === 'true' ? true : !toggleIsExpanded;
   });
 });

package/plugin/index.ts

@@ -30,7 +30,7 @@ import prebundleWorkers from 'vite-plugin-prebundle-workers';
 import { SpecLoader, startSpecLoader } from './specs';
 
 import type * as ReferenceSidebarsVirtualModule from 'virtual:stl-starlight-reference-sidebars';
-import { generateMissingRouteList } from '@stainless-api/docs-ui/routing';
+import { generateMissingRouteList, generateRouteList } from '@stainless-api/docs-ui/routing';
 import { buildAlgoliaIndex } from './buildAlgoliaIndex';
 
 export { generateAPILink } from './generateAPIReferenceLink';
@@ -357,13 +357,26 @@ function stlStarlightAstroIntegration(pluginConfig: NormalizedStainlessStarlight
           collectedErrors = null;
         }
 
+        const specComposite = await resolveSpecs();
+
+        // TODO: (multi-spec) support multiple specs
+        const spec = specComposite.listUniqueSpecs()[0]!.data.sdkJson;
+
+        const basePrefixInOutput = path.posix.join(astroBase, pluginConfig.basePath).replace(/^\/+/, '');
+        const routeList = generateRouteList({ spec });
+        const apiReferencePages = [
+          // overview page
+          path.posix.join(basePrefixInOutput, 'index.html'),
+          // all route pages
+          ...routeList.map((r) => path.posix.join(basePrefixInOutput, r.slug, 'index.html')),
+        ];
+
         const manifest = {
           astroBase,
+          apiReferencePages,
         };
         await writeFile(path.join(stainlessDir, 'stl-manifest.json'), JSON.stringify(manifest, null, 2));
 
-        const specComposite = await resolveSpecs();
-
         await buildAlgoliaIndex({
           specComposite,
           logger,
@@ -375,9 +388,6 @@ function stlStarlightAstroIntegration(pluginConfig: NormalizedStainlessStarlight
         // 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.
 
-        // TODO: (multi-spec) support multiple specs
-        const spec = specComposite.listUniqueSpecs()[0]!.data.sdkJson;
-
         const missingRoutes = generateMissingRouteList({
           spec,
           basePath: path.posix.join(astroBase, pluginConfig.basePath),

package/plugin/markdown/highlighter.ts

@@ -0,0 +1,100 @@
+import {
+  createHighlighter,
+  type HighlighterGeneric,
+  type ThemeInput,
+  type BundledTheme,
+  type BundledLanguage,
+} from 'shiki';
+import { HIGHLIGHT_THEMES } from 'virtual:stl-starlight-virtual-module';
+import { SupportedLanguageSyntaxes } from '@stainless-api/docs-ui/routing';
+import type { CreateShikiHighlighterOptions } from '@astrojs/markdown-remark';
+
+const STAINLESS_DOCS_JSON_THEME = {
+  name: 'stainless-docs-json',
+  colors: {
+    'editor.background': 'var(--stl-color-background)',
+    'editor.foreground': 'var(--stl-color-foreground)',
+  },
+
+  tokenColors: [
+    {
+      scope: ['comment', 'punctuation.definition.comment'],
+      settings: { foreground: 'var(--stl-color-foreground-muted)' },
+    },
+    // numbers, booleans, null
+    {
+      scope: ['constant.numeric', 'constant.language'],
+      settings: { foreground: 'var(--stl-color-orange-foreground)' },
+    },
+    // strings
+    {
+      scope: ['string', 'string.quoted', 'string.template'],
+      settings: { foreground: 'var(--stl-color-green-foreground)' },
+    },
+    // Keys, brackets
+    {
+      scope: ['support.type', 'meta'],
+      settings: { foreground: 'var(--stl-color-foreground)' },
+    },
+    // brackets
+    {
+      scope: ['meta'],
+      settings: { foreground: 'var(--stl-color-foreground-muted)' },
+    },
+    // built-in types
+    {
+      scope: ['support.type.builtin'],
+      settings: { foreground: 'var(--stl-color-purple-foreground)' },
+    },
+  ],
+} satisfies ThemeInput;
+
+// singleton
+let astroShikiHighlighter:
+  | HighlighterGeneric<BundledLanguage, BundledTheme>
+  | Promise<HighlighterGeneric<BundledLanguage, BundledTheme>>
+  | null = null;
+export async function getAstroHighlighter() {
+  if (astroShikiHighlighter) {
+    return astroShikiHighlighter;
+  }
+
+  astroShikiHighlighter = createHighlighter({
+    themes: [
+      HIGHLIGHT_THEMES?.dark ?? 'github-dark',
+      HIGHLIGHT_THEMES?.light ?? 'github-light',
+      STAINLESS_DOCS_JSON_THEME,
+    ],
+    langs: SupportedLanguageSyntaxes,
+  });
+
+  return astroShikiHighlighter;
+}
+
+function runHighlight({
+  highlighter,
+  content,
+  language,
+  themes,
+}: {
+  highlighter: HighlighterGeneric<BundledLanguage, BundledTheme>;
+  content: string;
+  language?: string;
+  themes?: CreateShikiHighlighterOptions['themes'] | Record<string, 'stainless-docs-json'>;
+}) {
+  return highlighter.codeToHtml(content, {
+    lang: language ?? 'javascript',
+    themes:
+      // Default to user-provided themes except in case of json
+      themes ??
+      (language === 'JSON'
+        ? { light: 'stainless-docs-json', dark: 'stainless-docs-json' }
+        : HIGHLIGHT_THEMES) ??
+      {},
+  });
+}
+
+export async function highlight(content: string, language?: string) {
+  const highlighter = await getAstroHighlighter();
+  return runHighlight({ highlighter, content, language });
+}

package/plugin/markdown/index.ts

@@ -0,0 +1,39 @@
+import { createMarkdownProcessor, type MarkdownProcessor } from '@astrojs/markdown-remark';
+import remarkGfmAlerts from 'remark-github-alerts';
+import { HIGHLIGHT_THEMES } from 'virtual:stl-starlight-virtual-module';
+
+// singleton
+let astroMarkdownProcessor: MarkdownProcessor;
+async function getAstroMarkdown() {
+  if (!astroMarkdownProcessor) {
+    astroMarkdownProcessor = await createMarkdownProcessor({
+      gfm: true,
+      remarkPlugins: [remarkGfmAlerts],
+      shikiConfig: { themes: HIGHLIGHT_THEMES },
+    });
+  }
+
+  return astroMarkdownProcessor;
+}
+
+export async function astroMarkdownRender(content: string) {
+  const md = await getAstroMarkdown();
+  const output = await md.render(content);
+
+  // Map GFM callouts to the closest Starlight equivalent
+  // TODO: this sucks; we should be rendering via ui-primitives callouts instead of ugly theme-incompatible starlight ones
+  output.code = output.code
+    .replaceAll('markdown-alert-caution', 'markdown-alert-danger')
+    .replaceAll('markdown-alert-warning', 'markdown-alert-caution')
+    .replaceAll('markdown-alert-important', 'markdown-alert-caution')
+    .replaceAll('markdown-alert-title', 'starlight-aside__title')
+    .replaceAll('markdown-alert-', 'starlight-aside--')
+    .replaceAll('markdown-alert', 'starlight-aside');
+
+  return output;
+}
+
+export async function astroMarkdownRenderText(content: string) {
+  const result = await astroMarkdownRender(content);
+  return result.code;
+}

package/plugin/react/Routing.tsx

@@ -1,18 +1,13 @@
 import * as React from 'react';
-import { marked, Tokens } from 'marked';
 import { getDocsLanguages } from '../helpers/multiSpec';
 
-import {
-  createMarkdownProcessor,
-  CreateShikiHighlighterOptions,
-  type MarkdownProcessor,
-} from '@astrojs/markdown-remark';
-import remarkGfmAlerts from 'remark-github-alerts';
+import { astroMarkdownRenderText } from '../markdown';
+import { highlight } from '../markdown/highlighter';
 
 import type { MarkdownHeading } from 'astro';
 import type { StarlightRouteData } from '@astrojs/starlight/route-data';
 import type * as SDKJSON from '@stainless/sdk-json';
-import { LanguageNames, SupportedLanguageSyntaxes, type DocsLanguage } from '@stainless-api/docs-ui/routing';
+import { LanguageNames, type DocsLanguage } from '@stainless-api/docs-ui/routing';
 
 import {
   generateRoute,
@@ -46,7 +41,6 @@ import { Dropdown } from '@stainless-api/docs/components';
 import {
   RESOLVED_API_REFERENCE_PATH,
   EXPAND_RESOURCES,
-  HIGHLIGHT_THEMES,
   BREADCRUMB_CONFIG,
   PROPERTY_SETTINGS,
   ENABLE_CONTEXT_MENU,
@@ -54,7 +48,6 @@ import {
   MIDDLEWARE,
 } from 'virtual:stl-starlight-virtual-module';
 import style from '@stainless-api/docs-ui/style';
-import { BundledTheme, createHighlighter, HighlighterGeneric, type BundledLanguage } from 'shiki';
 import {
   SnippetCode,
   SnippetContainer,
@@ -138,58 +131,6 @@ export function buildPageNavigation(resource: SDKJSON.Resource, depth: number =
   return [...output, ...subs];
 }
 
-async function renderMarkdown(content: string) {
-  const highlighter = await astroHighlight();
-
-  const renderer = {
-    code({ text, lang }: Tokens.Code) {
-      return shikiHighlight({
-        highlighter,
-        content: text,
-        language: lang,
-      });
-    },
-  };
-
-  marked.use({ renderer });
-  return marked.parse(content, {
-    gfm: true,
-  }) as string;
-}
-
-function shikiHighlight({
-  highlighter,
-  content,
-  language,
-  themes,
-}: {
-  highlighter: HighlighterGeneric<BundledLanguage, BundledTheme>;
-  content: string;
-  language?: string;
-  themes?: CreateShikiHighlighterOptions['themes'] | Record<string, 'stainless-docs-json'>;
-}) {
-  let _themes = themes;
-  if (!themes && language === 'json') {
-    _themes = {
-      light: 'stainless-docs-json',
-      dark: 'stainless-docs-json',
-    };
-  }
-
-  if (!_themes) {
-    _themes = HIGHLIGHT_THEMES;
-  }
-  return highlighter.codeToHtml(content, {
-    lang: language ?? 'javascript',
-    themes: _themes || {},
-  });
-}
-
-async function highlight(content: string, language?: string) {
-  const highlighter = await astroHighlight();
-  return shikiHighlight({ highlighter, content, language });
-}
-
 export function SDKSelectReactComponent({
   selected,
   languages,
@@ -295,7 +236,7 @@ export function RenderSpecOverview({ spec, language }: { spec: SDKJSON.Spec; lan
     <DocsProvider spec={spec} language={language ?? 'node'}>
       <ComponentProvider components={componentOverrides}>
         <NavigationProvider basePath={RESOLVED_API_REFERENCE_PATH}>
-          <MarkdownProvider render={renderMarkdown} highlight={highlight}>
+          <MarkdownProvider render={astroMarkdownRenderText} highlight={highlight}>
             <div className={style.Overview}>
               {resources
                 .filter(({ resource }) => !resource.name.startsWith('$'))
@@ -336,7 +277,7 @@ export function RenderSpec({
   const resource = getResourceFromSpec(path, spec);
 
   if (!resource || !parsed) {
-    console.warn(`Could not find resource or parsed path for '${path}'`); // eslint-disable-line @eslint-react/purity
+    console.warn(`Could not find resource or parsed path for '${path}'`);
     return null;
   }
 
@@ -351,7 +292,7 @@ export function RenderSpec({
     >
       <ComponentProvider components={componentOverrides}>
         <NavigationProvider basePath={RESOLVED_API_REFERENCE_PATH} selectedPath={path}>
-          <MarkdownProvider render={renderMarkdown} highlight={highlight}>
+          <MarkdownProvider render={astroMarkdownRenderText} highlight={highlight}>
             {
               <div className="stldocs-root stl-ui-not-prose">
                 <div className="stl-page-nav-container">
@@ -388,7 +329,7 @@ export function RenderMethod({ path }: { path: string }) {
   const resource = getResourceFromSpec(path, spec);
 
   if (!resource || !parsed) {
-    console.warn(`Could not find resource or parsed path for '${path}'`); // eslint-disable-line @eslint-react/purity
+    console.warn(`Could not find resource or parsed path for '${path}'`);
     return null;
   }
 
@@ -412,96 +353,3 @@ export async function getReadmeContent(spec: SDKJSON.Spec, language: DocsLanguag
 
   return spec.readme[language];
 }
-
-let astroShikiHighlighter:
-  | HighlighterGeneric<BundledLanguage, BundledTheme>
-  | Promise<HighlighterGeneric<BundledLanguage, BundledTheme>>
-  | null = null;
-
-async function astroHighlight() {
-  if (astroShikiHighlighter) {
-    return astroShikiHighlighter;
-  }
-
-  astroShikiHighlighter = createHighlighter({
-    themes: [
-      HIGHLIGHT_THEMES?.dark ?? 'github-dark',
-      HIGHLIGHT_THEMES?.light ?? 'github-light',
-      {
-        name: 'stainless-docs-json',
-        colors: {
-          'editor.background': 'var(--stl-color-background)',
-          'editor.foreground': 'var(--stl-color-foreground)',
-        },
-
-        tokenColors: [
-          {
-            scope: ['comment', 'punctuation.definition.comment'],
-            settings: { foreground: 'var(--stl-color-foreground-muted)' },
-          },
-          // numbers, booleans, null
-          {
-            scope: ['constant.numeric', 'constant.language'],
-            settings: { foreground: 'var(--stl-color-orange-foreground)' },
-          },
-          // strings
-          {
-            scope: ['string', 'string.quoted', 'string.template'],
-            settings: { foreground: 'var(--stl-color-green-foreground)' },
-          },
-          // Keys, brackets
-          {
-            scope: ['support.type', 'meta'],
-            settings: { foreground: 'var(--stl-color-foreground)' },
-          },
-          // brackets
-          {
-            scope: ['meta'],
-            settings: { foreground: 'var(--stl-color-foreground-muted)' },
-          },
-          // built-in types
-          {
-            scope: ['support.type.builtin'],
-            settings: { foreground: 'var(--stl-color-purple-foreground)' },
-          },
-        ],
-      },
-    ],
-    langs: SupportedLanguageSyntaxes,
-  });
-
-  return astroShikiHighlighter;
-}
-
-// Astro's markdown processor is a singleton
-// Need to cache it instead of instantiating per request
-let astroMarkdownProcessor: MarkdownProcessor;
-async function astroMarkdown() {
-  if (!astroMarkdownProcessor) {
-    astroMarkdownProcessor = await createMarkdownProcessor({
-      gfm: true,
-      remarkPlugins: [remarkGfmAlerts],
-      shikiConfig: {
-        themes: HIGHLIGHT_THEMES,
-      },
-    });
-  }
-
-  return astroMarkdownProcessor;
-}
-
-export async function astroMarkdownRender(content: string) {
-  const md = await astroMarkdown();
-  const output = await md.render(content);
-
-  // Map GFM callouts to the closest Starlight equivalent
-  output.code = output.code
-    .replaceAll('markdown-alert-caution', 'markdown-alert-danger')
-    .replaceAll('markdown-alert-warning', 'markdown-alert-caution')
-    .replaceAll('markdown-alert-important', 'markdown-alert-caution')
-    .replaceAll('markdown-alert-title', 'starlight-aside__title')
-    .replaceAll('markdown-alert-', 'starlight-aside--')
-    .replaceAll('markdown-alert', 'starlight-aside');
-
-  return output;
-}

package/plugin/routes/Docs.astro

@@ -1,6 +1,7 @@
 ---
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
-import { getReadmeContent, buildPageNavigation, RenderSpec, astroMarkdownRender } from '../react/Routing';
+import { getReadmeContent, buildPageNavigation, RenderSpec } from '../react/Routing';
+import { astroMarkdownRender } from '../markdown';
 import { getResourceFromSpec } from '@stainless-api/docs-ui/utils';
 import { parseRoute, parseStainlessPath } from '@stainless-api/docs-ui/routing';
 import {