@stainless-api/docs 0.1.0-beta.135 → 0.1.0-beta.136

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @stainless-api/docs
 
+## 0.1.0-beta.136
+
+### Minor Changes
+
+- 5a6e598: [og image] migrate Takumi to v1
+
+### Patch Changes
+
+- 8b7aaff: Adds markdown representation for overview
+- 23bd8f7: Update preview worker
+
 ## 0.1.0-beta.135
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.135",
+  "version": "0.1.0-beta.136",
   "publishConfig": {
     "access": "public"
   },
@@ -38,14 +38,14 @@
   },
   "peerDependencies": {
     "@astrojs/starlight": ">=0.38.0",
-    "@takumi-rs/image-response": ">=0.66.6",
+    "takumi-js": ">=1.0.5",
     "astro": ">=6.0.0",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
     "vite": ">=7.3.1"
   },
   "peerDependenciesMeta": {
-    "@takumi-rs/image-response": {
+    "takumi-js": {
       "optional": true
     }
   },
@@ -57,8 +57,8 @@
     "@streamparser/json-whatwg": "^0.0.22",
     "cheerio": "^1.2.0",
     "clsx": "^2.1.1",
-    "dotenv": "17.4.1",
-    "lucide-react": "^0.577.0",
+    "dotenv": "17.4.2",
+    "lucide-react": "^1.8.0",
     "motion": "^12.38.0",
     "node-html-parser": "^7.1.0",
     "rehype-parse": "^9.0.1",
@@ -78,12 +78,12 @@
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.8",
-    "@takumi-rs/image-response": "^0.73.1",
+    "takumi-js": "^1.0.11",
     "@types/node": "24.12.2",
     "@types/react": "19.2.14",
     "@types/react-dom": "^19.2.3",
     "@types/react-syntax-highlighter": "^15.5.13",
-    "astro": "^6.1.5",
+    "astro": "^6.1.7",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
     "typescript": "6.0.2",

package/plugin/index.ts

@@ -135,6 +135,12 @@ function stlStarlightAstroIntegration(pluginConfig: NormalizedStainlessStarlight
           prerender: pluginConfig.experimentalPrerender ? command === 'build' : false,
         });
 
+        injectRoute({
+          pattern: `${pluginConfig.basePath}/index.md`,
+          entrypoint: resolveSrcFile('/plugin/routes/markdown.ts'),
+          prerender: pluginConfig.experimentalPrerender ? command === 'build' : false,
+        });
+
         const astroFile = command === 'build' ? 'DocsStatic' : 'Docs';
         injectRoute({
           pattern: `${pluginConfig.basePath}/[...slug]`,

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,
 };
 ---
 

package/plugin/routes/markdown.ts

@@ -1,14 +1,23 @@
 import type { APIRoute, GetStaticPaths } from 'astro';
+import type { Node } from '@markdoc/markdoc';
 import { getReadmeContent } from '../react/Routing';
-import { getResourceFromSpec } from '@stainless-api/docs-ui/utils';
+import { getResourceFromSpec, isResourceEmpty } from '@stainless-api/docs-ui/utils';
 
 import { renderMarkdown } from '@stainless-api/docs-ui/markdown';
+import * as md from '@stainless-api/docs-ui/markdown/md';
 
-import { parseStainlessPath, type DocsLanguage } from '@stainless-api/docs-ui/routing';
+import { parseStainlessPath, generateRoute, type DocsLanguage } from '@stainless-api/docs-ui/routing';
 import type { EnvironmentType } from '@stainless-api/docs-ui/markdown/utils';
-import { PROPERTY_SETTINGS, MIDDLEWARE } from 'virtual:stl-starlight-virtual-module';
+import {
+  PROPERTY_SETTINGS,
+  MIDDLEWARE,
+  RESOLVED_API_REFERENCE_PATH,
+} from 'virtual:stl-starlight-virtual-module';
 import { generateAllDocsRoutes } from '../helpers/generateDocsRoutes';
 import { getSDKJSONInSSR } from '../specs/fetchSpecSSR';
+import Markdoc from '@markdoc/markdoc';
+import type * as SDKJSON from '@stainless/sdk-json';
+import { API_REFERENCE_BASE_PATH } from 'virtual:stl-docs-virtual-module';
 
 type RouteProps = {
   stainlessPath: string;
@@ -21,20 +30,41 @@ export const getStaticPaths = (async () => {
   return paths;
 }) satisfies GetStaticPaths;
 
-export const GET: APIRoute<RouteProps> = async ({ props }) => {
-  const spec = await getSDKJSONInSSR(props.language);
+function renderLink(stainlessPath: string, title: string) {
+  const href = generateRoute(RESOLVED_API_REFERENCE_PATH, 'http', stainlessPath);
+  return href ? md.link(`${href}/index.md`, title) : md.text(title);
+}
 
-  if (props.kind === 'readme') {
-    const readmeContent = await getReadmeContent(spec, props.language);
-    return new Response(readmeContent, {
-      headers: { 'Content-Type': 'text/plain' },
-    });
+function renderOverviewResource(resource: SDKJSON.Resource, topLevel: boolean): Node[] {
+  const link = renderLink(resource.stainlessPath, resource.title);
+
+  const methodItems = Object.values(resource.methods).map((method) =>
+    md.item(md.paragraph(renderLink(method.stainlessPath, method.title))),
+  );
+
+  const subItems = Object.values(resource.subresources ?? {})
+    .filter((sub) => !isResourceEmpty(sub))
+    .flatMap((sub) => renderOverviewResource(sub, false));
+
+  const nestedItems = [...methodItems, ...subItems];
+  const list = nestedItems.length > 0 ? [md.list(...nestedItems)] : [];
+
+  return topLevel ? [md.heading(2, [link]), ...list] : [md.item(md.paragraph(link), ...list)];
+}
+
+function renderOverview({ spec }: EnvironmentType): string {
+  const output: Node[] = [md.heading(1, 'API Reference')];
+
+  for (const resource of Object.values(spec.resources)) {
+    if (!isResourceEmpty(resource)) output.push(...renderOverviewResource(resource, true));
   }
 
-  const parsed = parseStainlessPath(props.stainlessPath);
-  const resource = getResourceFromSpec(props.stainlessPath, spec);
+  const doc = new Markdoc.Ast.Node('document', {}, output);
+  return Markdoc.format(doc);
+}
 
-  if (!resource) throw new Error('Invalid route');
+export const GET: APIRoute<RouteProps> = async ({ props, routePattern }) => {
+  const spec = await getSDKJSONInSSR(props.language ?? 'http');
 
   const env: EnvironmentType = {
     spec,
@@ -48,6 +78,25 @@ export const GET: APIRoute<RouteProps> = async ({ props }) => {
     },
   };
 
+  if (routePattern === `${API_REFERENCE_BASE_PATH}/index.md`) {
+    const content = renderOverview({ ...env, language: 'http' });
+    return new Response(content, {
+      headers: { 'Content-Type': 'text/plain' },
+    });
+  }
+
+  if (props.kind === 'readme') {
+    const readmeContent = await getReadmeContent(spec, props.language);
+    return new Response(readmeContent, {
+      headers: { 'Content-Type': 'text/plain' },
+    });
+  }
+
+  const parsed = parseStainlessPath(props.stainlessPath);
+  const resource = getResourceFromSpec(props.stainlessPath, spec);
+
+  if (!resource) throw new Error('Invalid route');
+
   const target = props.kind === 'http_method' && parsed?.method ? resource.methods[parsed.method]! : resource;
   const output = renderMarkdown(env, target);