@stainless-api/docs 0.1.0-beta.99 → 1.0.0-beta.141

package/plugin/react/Routing.tsx

@@ -1,31 +1,19 @@
 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,
-  parseStainlessPath,
-  walkTree,
-  getLanguageSnippet,
-} from '@stainless-api/docs-ui/routing';
+import { parseStainlessPath, getLanguageSnippet } from '@stainless-api/docs-ui/routing';
 
 import {
   DocsProvider,
   MarkdownProvider,
   NavigationProvider,
-  useSpec,
   type ContentPanelLayout,
 } from '@stainless-api/docs-ui/contexts';
 
@@ -45,15 +33,13 @@ import { Dropdown } from '@stainless-api/docs/components';
 
 import {
   RESOLVED_API_REFERENCE_PATH,
-  EXPAND_RESOURCES,
-  HIGHLIGHT_THEMES,
   BREADCRUMB_CONFIG,
   PROPERTY_SETTINGS,
   ENABLE_CONTEXT_MENU,
   EXPERIMENTAL_COLLAPSIBLE_METHOD_DESCRIPTIONS,
+  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,
@@ -67,66 +53,6 @@ import { AIDropdown } from '../../stl-docs/components/AIDropdown';
 import { ChevronsUpDownIcon } from 'lucide-react';
 import { MethodDescription } from '../components/MethodDescription';
 
-function isResourceNonEmpty(resource: SDKJSON.Resource) {
-  return (
-    Object.keys(resource.methods ?? {}).length > 0 ||
-    Object.keys(resource.subresources ?? {}).length > 0 ||
-    Object.keys(resource.models ?? {}).length > 0
-  );
-}
-
-type SidebarEntry = StarlightRouteData['sidebar'][number];
-
-export function buildSidebar(
-  basePath: string,
-  language: DocsLanguage,
-  current: string,
-  spec: SDKJSON.Spec,
-  resources?: Record<string, SDKJSON.Resource>,
-  nested?: boolean,
-): StarlightRouteData['sidebar'] {
-  const totalRoutes = Array.from(walkTree(spec, false)).filter(
-    (item) => item.data.kind === 'http_method',
-  ).length;
-
-  return Object.values(resources ?? spec.resources ?? [])
-    .filter((resource) => isResourceNonEmpty(resource))
-    .sort((a, b) => (a.name.startsWith('$') === b.name.startsWith('$') ? 0 : a.name.startsWith('$') ? 1 : -1))
-    .map((resource) => {
-      const subs = buildSidebar(basePath, language, current, spec, resource.subresources, true);
-
-      const overview: SidebarEntry = {
-        type: 'link',
-        isCurrent: current === resource.stainlessPath,
-        attrs: { 'data-stldocs-overview': resource.name },
-        label: 'Overview',
-        href: generateRoute(basePath, language, resource.stainlessPath) ?? basePath,
-        badge: undefined,
-      };
-
-      const meths: SidebarEntry[] = Object.values(resource.methods ?? [])
-        .filter((method) => spec.decls?.[language]?.[method.stainlessPath])
-        .map((method) => ({
-          type: 'link',
-          isCurrent: current === method.stainlessPath,
-          attrs: { 'data-stldocs-method': method.httpMethod },
-          label: method.summary ?? method.name,
-          href: generateRoute(basePath, language, method.stainlessPath) ?? basePath,
-          badge: undefined,
-        }));
-
-      const shouldExpand = EXPAND_RESOURCES ?? totalRoutes < 20;
-
-      return {
-        type: 'group',
-        label: resource.title,
-        badge: undefined,
-        collapsed: !shouldExpand || nested === true,
-        entries: [...(resources ? [] : [overview]), ...meths, ...subs],
-      };
-    });
-}
-
 export function buildPageNavigation(resource: SDKJSON.Resource, depth: number = 2): MarkdownHeading[] {
   const output: MarkdownHeading[] = [{ depth, slug: resource.stainlessPath, text: resource.title }];
 
@@ -137,58 +63,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,
@@ -268,6 +142,7 @@ const componentOverrides = {
   SnippetFooter,
   SnippetResponse,
   ...(EXPERIMENTAL_COLLAPSIBLE_METHOD_DESCRIPTIONS ? { MethodDescription } : {}),
+  ...MIDDLEWARE.componentOverrides,
 } satisfies React.ComponentProps<typeof ComponentProvider>['components'];
 
 export function RenderLibraries({ metadata }: { metadata: SpecMetadata }) {
@@ -293,7 +168,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('$'))
@@ -340,7 +215,7 @@ export function RenderSpec({
 
   return (
     <DocsProvider
-      spec={spec as SDKJSON.Spec}
+      spec={spec}
       language={language ?? 'node'}
       settings={{
         contentPanelLayout,
@@ -349,12 +224,12 @@ 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">
                   <SDKBreadcrumbs
-                    spec={spec as SDKJSON.Spec}
+                    spec={spec}
                     currentPath={currentPath}
                     basePath={RESOLVED_API_REFERENCE_PATH}
                     config={BREADCRUMB_CONFIG}
@@ -378,22 +253,6 @@ export function RenderSpec({
   );
 }
 
-export function RenderMethod({ path }: { path: string }) {
-  const spec = useSpec();
-  if (!spec) return null;
-
-  const parsed = parseStainlessPath(path);
-  const resource = getResourceFromSpec(path, spec);
-
-  if (!resource || !parsed) {
-    console.warn(`Could not find resource or parsed path for '${path}'`);
-    return null;
-  }
-
-  const method = resource.methods[parsed.method!]!;
-  return <SDKMethod method={method} />;
-}
-
 export async function getReadmeContent(spec: SDKJSON.Spec, language: DocsLanguage) {
   const repoUrl = spec.metadata?.[language]?.repo_url;
 
@@ -410,96 +269,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: [
-      'github-light',
-      'github-dark',
-      {
-        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/referencePlaceholderUtils.ts

@@ -21,7 +21,7 @@ export function makePlaceholderItems(id: number) {
 
 type StarlightConfig = Parameters<typeof starlight>[0];
 
-export type SidebarConfigEntry = Exclude<StarlightConfig['sidebar'], undefined>[number];
+type SidebarConfigEntry = Exclude<StarlightConfig['sidebar'], undefined>[number];
 
 export function getAPIReferencePlaceholderItemFromSidebarConfig(
   sidebar: SidebarConfigEntry[],

package/plugin/replaceSidebarPlaceholderMiddleware.ts

@@ -32,7 +32,7 @@ function markCurrentItems(sidebar: SidebarEntry[], currentSlug: string) {
   return mutableSidebarInstance;
 }
 
-export const onRequest = defineRouteMiddleware(async (context) => {
+export const onRequest = defineRouteMiddleware((context) => {
   // if using content collection schema, use: context.locals.starlightRoute.entry.data.stainlessStarlight
   // this worked without collections but relied on hijacking starlightRoute: context.props.frontmatter.stainlessStarlight
   const slug = path.posix.join(import.meta.env.BASE_URL ?? '', `/${context.locals.starlightRoute.id}`); // same as .slug but not deprecated

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 {
@@ -120,3 +121,4 @@ if (props.kind === 'http_method' && props.stainlessPath) {
 <script src="../globalJs/tooltip.ts"></script>
 <script src="../globalJs/code-snippets.ts"></script>
 <script src="../globalJs/method-descriptions.ts"></script>
+<script src="../globalJs/summary-selection-tweak.ts"></script>

package/plugin/routes/Overview.astro

@@ -29,7 +29,7 @@ const metadata: SpecMetadata = langsWithSpecs.map(({ language, spec }) => [
 
 // PageTitle override will skip rendering the default Starlight title
 Astro.locals._stlStarlightPage = {
-  hasMarkdownRoute: false,
+  hasMarkdownRoute: true,
 };
 ---
 
@@ -41,11 +41,17 @@ Astro.locals._stlStarlightPage = {
   }}
 >
   <div class="stl-overview">
-    <h3>Libraries</h3>
+    {
+      metadata.length > 0 && (
+        <>
+          <h3>Libraries</h3>
 
-    <div class="stldocs-root language-blocks stl-ui-not-prose not-content">
-      <RenderLibraries metadata={metadata} />
-    </div>
+          <div class="stldocs-root language-blocks stl-ui-not-prose not-content">
+            <RenderLibraries metadata={metadata} />
+          </div>
+        </>
+      )
+    }
 
     <h3>API Overview</h3>
 
@@ -62,8 +68,9 @@ Astro.locals._stlStarlightPage = {
     gap: 1rem;
     margin-top: 2rem;
 
-    .stldocs-language-block {
-      width: 350px;
+    > * {
+      width: 0;
+      flex: 1 1 350px;
     }
   }
 

package/plugin/routes/llms.ts

@@ -0,0 +1,186 @@
+import type { APIRoute } from 'astro';
+import { getCollection } from 'astro:content';
+import { base as ASTRO_BASE } from 'astro:config/server';
+import { SITE_TITLE, API_REFERENCE_BASE_PATH } from 'virtual:stl-docs-virtual-module';
+import { LLMS_TXT_DESCRIPTION, LLMS_TXT_DETAIL_THRESHOLD } from 'virtual:stl-starlight-virtual-module';
+import { getSDKJSONInSSR } from '../specs/fetchSpecSSR';
+import Markdoc from '@markdoc/markdoc';
+import type { Node } from '@markdoc/markdoc';
+import * as md from '@stainless-api/docs-ui/markdown/md';
+import type * as SDKJSON from '@stainless/sdk-json';
+import { generateRoute, walkTree } from '@stainless-api/docs-ui/routing';
+
+export const prerender = true;
+
+function joinUrlParts(...parts: (string | boolean | null | undefined)[]) {
+  return (
+    '/' +
+    parts
+      .map((p) => {
+        if (typeof p === 'string') {
+          return p.split('/');
+        }
+        return p;
+      })
+      .flat()
+      .filter(Boolean)
+      .join('/')
+  );
+}
+
+export type ProsePageEntry = {
+  id: string;
+  title: string;
+  description?: string;
+};
+
+function isResourceEmpty(resource: SDKJSON.Resource) {
+  return Object.values(resource.methods).length < 1 && Object.values(resource.subresources ?? {}).length < 1;
+}
+
+function trimPath(path: string) {
+  return path.endsWith('/') ? path.slice(0, -1) : path;
+}
+
+function apiHref(basePath: string, language: string, stainlessPath: string) {
+  const href = generateRoute(basePath, language, stainlessPath);
+  if (!href) return null;
+  return joinUrlParts(ASTRO_BASE, href, 'index.md');
+}
+
+function linkListItem(title: string, url: string, description?: string): Node {
+  const children = [md.link(url, title)];
+  if (description) children.push(md.text(`: ${description}`));
+  return md.item(md.inline(...children));
+}
+
+function generateProseIndex(routes: ProsePageEntry[], detailed: boolean) {
+  const pageEntryLink = (page: ProsePageEntry) =>
+    linkListItem(
+      page.title,
+      joinUrlParts(ASTRO_BASE, page.id === 'index' ? null : page.id, 'index.md'),
+      detailed ? page.description : undefined,
+    );
+  return [md.heading(2, 'Docs'), md.list(...routes.map(pageEntryLink))];
+}
+
+function renderMethods(basePath: string, language: string, methods: Record<string, SDKJSON.Method>) {
+  const output: Node[] = [];
+
+  for (const method of Object.values(methods)) {
+    const href = apiHref(basePath, language, method.stainlessPath);
+    if (href) output.push(linkListItem(method.title, href, method.summary));
+  }
+
+  return md.list(...output);
+}
+
+function renderResource(
+  basePath: string,
+  language: string,
+  detailed: boolean,
+  resource: SDKJSON.Resource,
+): Node {
+  const href = apiHref(basePath, language, resource.stainlessPath);
+  const output = [md.paragraph(href ? md.link(href, resource.title) : md.text(resource.title))];
+  if (resource.methods && detailed) output.push(renderMethods(basePath, language, resource.methods));
+  if (resource.subresources) output.push(renderSubs(basePath, language, detailed, resource.subresources));
+  return md.item(...output);
+}
+
+function renderSubs(
+  basePath: string,
+  language: string,
+  detailed: boolean,
+  resources: Record<string, SDKJSON.Resource>,
+): Node {
+  return md.list(
+    ...Object.values(resources)
+      .filter((res) => !isResourceEmpty(res))
+      .map((sub) => renderResource(basePath, language, detailed, sub)),
+  );
+}
+
+function renderLanguageNote(basePath: string, languages: string[]) {
+  return [
+    md.paragraph(
+      md.text('Links below point to language-neutral HTTP documentation. '),
+      md.text(
+        'SDK-specific docs follow the same URL structure with the language inserted after the base path: ',
+      ),
+      md.code(`${trimPath(basePath)}/{language}/resources/...`),
+      md.text('.'),
+    ),
+    md.paragraph(md.text(`Available languages: ${languages.join(', ')}`)),
+  ];
+}
+
+function generateRefIndex(
+  basePath: string,
+  languages: string[],
+  language: string,
+  detailed: boolean,
+  spec: SDKJSON.Spec,
+) {
+  const output = [md.heading(2, 'API Reference'), ...renderLanguageNote(basePath, languages)];
+
+  for (const resource of Object.values(spec.resources)) {
+    if (isResourceEmpty(resource)) continue;
+    const href = apiHref(basePath, language, resource.stainlessPath);
+    output.push(md.heading(3, [href ? md.link(href, resource.title) : md.text(resource.title)]));
+    if (resource.methods && detailed) output.push(renderMethods(basePath, language, resource.methods));
+    if (resource.subresources) output.push(renderSubs(basePath, language, detailed, resource.subresources));
+  }
+
+  return output;
+}
+
+function generateMarkdownIndex({
+  siteTitle,
+  description,
+  basePath,
+  languages,
+  spec,
+  detailed,
+  proseRoutes,
+}: {
+  siteTitle: string;
+  description: string | null;
+  basePath: string;
+  languages: string[];
+  spec: SDKJSON.Spec;
+  detailed: boolean;
+  proseRoutes: ProsePageEntry[];
+}) {
+  const output: Node[] = [md.heading(1, siteTitle)];
+  if (description) output.push(md.paragraph(md.text(description)));
+  if (proseRoutes.length > 0) output.push(...generateProseIndex(proseRoutes, detailed));
+  if (languages.length > 0) output.push(...generateRefIndex(basePath, languages, 'http', detailed, spec));
+
+  const doc = new Markdoc.Ast.Node('document', {}, output);
+  return Markdoc.format(doc);
+}
+
+export const GET: APIRoute = async () => {
+  const [docsCollection, spec] = await Promise.all([getCollection('docs'), getSDKJSONInSSR('http')]);
+  const apiEntries = [...walkTree(spec)].filter((n) => n.data.kind !== 'model');
+  const proseRoutes = docsCollection.map((entry) => ({
+    id: entry.id,
+    title: entry.data.title,
+    description: entry.data.description,
+  }));
+
+  const content = generateMarkdownIndex({
+    siteTitle: SITE_TITLE,
+    description: LLMS_TXT_DESCRIPTION,
+    basePath: API_REFERENCE_BASE_PATH,
+    languages: spec.docs?.languages ?? [],
+    detailed: apiEntries.length + proseRoutes.length < LLMS_TXT_DETAIL_THRESHOLD,
+    spec,
+    proseRoutes,
+  });
+
+  return new Response(content, {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  });
+};