@stainless-api/docs 0.1.0-beta.14 → 0.1.0-beta.16

package/resolveSrcFile.ts

@@ -0,0 +1,10 @@
+import { join } from 'path';
+const dirName = import.meta.dirname;
+/**
+ * Resolve a source file path relative to the stl-starlight package.
+ * @param projectPath - The relative path to the source file.
+ * @returns The absolute path to the source file.
+ */
+export function resolveSrcFile(...projectPath: string[]) {
+  return join(dirName, ...projectPath);
+}

package/shared/getSharedLogger.ts

@@ -0,0 +1,15 @@
+import { AstroIntegrationLogger } from 'astro';
+
+let sharedLogger: AstroIntegrationLogger | null = null;
+
+// This is probably temporary, but it's a quick way to share a logger between our many integrations
+// we want to share a logger so they have the same "stainless" label
+
+export function setSharedLogger(logger: AstroIntegrationLogger) {
+  sharedLogger = logger;
+}
+
+// a fallback is probably not required, but it's a good safeguard in case we somehow call a logger before the shared logger is set
+export function getSharedLogger({ fallback }: { fallback: AstroIntegrationLogger }) {
+  return sharedLogger ?? fallback;
+}

package/shared/terminalUtils.ts

@@ -0,0 +1,3 @@
+export function bold(text: string) {
+  return `\x1b[1m${text}\x1b[0m`;
+}

package/stl-docs/components/AIDropdown.tsx

@@ -0,0 +1,52 @@
+import { DropdownButton } from '@stainless-api/ui-primitives';
+import { CopyIcon } from 'lucide-react';
+import { ChatGPTIcon } from './icons/chat-gpt';
+import { ClaudeIcon } from './icons/claude';
+import { MarkdownIcon } from './icons/markdown';
+import React from 'react';
+
+import { getAIDropdownOptions, type DropdownIcon } from '../../plugin/globalJs/ai-dropdown-options';
+
+const iconMap: { [key in DropdownIcon]: React.ReactNode } = {
+  markdown: <MarkdownIcon />,
+  copy: <CopyIcon size={16} />,
+  claude: <ClaudeIcon />,
+  chatgpt: <ChatGPTIcon />,
+};
+
+const { primaryAction, groups } = getAIDropdownOptions();
+
+function ItemLabel({ label }: { label: string[] }) {
+  const isExternal = label.length > 1;
+  return (
+    <DropdownButton.MenuItemText subtle={isExternal}>
+      {label[0]}
+      {isExternal && <strong>{label[1]}</strong>}
+    </DropdownButton.MenuItemText>
+  );
+}
+
+export function AIDropdown() {
+  return (
+    <DropdownButton data-dropdown-id="ai-dropdown-button">
+      <DropdownButton.PrimaryAction>
+        {iconMap[primaryAction.icon]}
+        <DropdownButton.PrimaryActionText>{primaryAction.label}</DropdownButton.PrimaryActionText>
+      </DropdownButton.PrimaryAction>
+      <DropdownButton.Trigger />
+      <DropdownButton.Menu>
+        {groups.map((group) => (
+          <React.Fragment key={group.reactKey}>
+            {group.options.map((option) => (
+              <DropdownButton.MenuItem value={option.id} isExternalLink key={option.id}>
+                <DropdownButton.MenuItemIcon>{iconMap[option.icon]}</DropdownButton.MenuItemIcon>
+                <ItemLabel label={option.label} />
+              </DropdownButton.MenuItem>
+            ))}
+            {group.isLast ? null : <hr />}
+          </React.Fragment>
+        ))}
+      </DropdownButton.Menu>
+    </DropdownButton>
+  );
+}

package/stl-docs/components/Head.astro

@@ -0,0 +1,9 @@
+---
+import Default from '@astrojs/starlight/components/Head.astro';
+---
+
+<Default />
+<script>
+  import { wireAIDropdown } from '../../plugin/globalJs/ai-dropdown-options.ts';
+  wireAIDropdown();
+</script>

package/stl-docs/components/PageTitle.astro

@@ -0,0 +1,67 @@
+---
+import { ENABLE_CONTEXT_MENU, ENABLE_PROSE_MARKDOWN_RENDERING } from 'virtual:stl-docs-virtual-module';
+import type { StarlightRouteData } from '@astrojs/starlight/route-data';
+import Default from '@astrojs/starlight/components/PageTitle.astro';
+import { ContentBreadcrumbs } from './ContentBreadcrumbs';
+import { AIDropdown } from './AIDropdown';
+
+function sidebarHasEntry(sidebarEntry: StarlightRouteData['sidebar'], currentPath?: string) {
+  if (!currentPath) return false;
+  const normalizePath = (path: string) => {
+    return path.endsWith('/') ? path : path + '/';
+  };
+
+  const normalizedCurrent = normalizePath(currentPath);
+
+  for (const entry of sidebarEntry) {
+    if (entry.type === 'link') {
+      const normalizedHref = normalizePath(entry.href);
+      if (normalizedHref === normalizedCurrent) {
+        return true;
+      }
+    } else if (entry.type === 'group') {
+      const hasInGroup = sidebarHasEntry(entry.entries, currentPath);
+      if (hasInGroup) return true;
+    }
+  }
+
+  return false;
+}
+
+// @ts-expect-error - _stlStarlightPage isn't typed
+const skipRenderingStarlightTitle = (Astro.locals._stlStarlightPage?.skipRenderingStarlightTitle ??
+  false) as boolean;
+
+// @ts-expect-error - _stlStarlightPage isn't typed
+const hasMarkdownRoute = (Astro.locals._stlStarlightPage?.hasMarkdownRoute ?? true) as boolean;
+// ⬆️ hopefully this is temporary. But for now, we don't have a markdown representation of the API reference overview page
+
+const currentPath = Astro.url.pathname;
+
+function shouldShowAIDropdown() {
+  // Hide if there is no associated sidebar entry. This applies to pages like the 404 page.
+  const hasSidebarEntry = sidebarHasEntry(Astro.locals.starlightRoute.sidebar, currentPath);
+  if (!hasSidebarEntry) return false;
+
+  if (!hasMarkdownRoute) return false;
+
+  if (!ENABLE_PROSE_MARKDOWN_RENDERING) return false;
+  if (!ENABLE_CONTEXT_MENU) return false;
+
+  return true;
+}
+
+const showAIDropdown = shouldShowAIDropdown();
+---
+
+{
+  skipRenderingStarlightTitle ? null : (
+    <>
+      <div class="stl-ui-not-prose stl-page-nav-container stl-prose-page-nav-container">
+        <ContentBreadcrumbs currentPath={currentPath} sidebarEntry={Astro.locals.starlightRoute.sidebar} />
+        {showAIDropdown && <AIDropdown />}
+      </div>
+      <Default />
+    </>
+  )
+}

package/stl-docs/components/content-panel/ContentPanel.astro

@@ -1,20 +1,9 @@
 ---
-import { ContentBreadcrumbs } from './ContentBreadcrumbs';
-import { ProseAIDropdown } from './ProseAIDropdown';
-import { INCLUDE_AI_DROPDOWN_OPTIONS } from 'virtual:stl-docs-virtual-module';
-const currentPath = Astro.url.pathname;
+
 ---
 
 <div class="content-panel">
   <div class="sl-container stl-ui-prose">
-    <div class="stl-ui-not-prose stl-page-nav-container stl-prose-page-nav-container">
-      <ContentBreadcrumbs currentPath={currentPath} sidebarEntry={Astro.locals.starlightRoute.sidebar} />
-      {
-        INCLUDE_AI_DROPDOWN_OPTIONS && (
-          <ProseAIDropdown currentPath={currentPath} sidebarEntry={Astro.locals.starlightRoute.sidebar} />
-        )
-      }
-    </div>
     <slot />
   </div>
 </div>
@@ -38,32 +27,16 @@ const currentPath = Astro.url.pathname;
     }
   }
   .content-panel {
-    padding: 0 0.5rem 0 var(--sl-content-pad-x);
+    padding: 0 var(--sl-content-pad-x) 0 var(--sl-content-pad-x);
   }
 
-  .stl-prose-page-nav-container {
-    padding: 1rem 0 0;
+  @media (min-width: 50rem) {
+    .content-panel {
+      padding: 0 0 0 var(--sl-content-pad-x);
+    }
   }
-</style>
 
-<style is:global>
-  .content-panel:nth-of-type(2) .stl-page-nav-container {
-    display: none;
+  .stl-prose-page-nav-container {
+    padding: 1rem 0 0;
   }
 </style>
-
-<script>
-  import { initDropdownButton } from '@stainless-api/ui-primitives/scripts';
-  import { getPageLoadEvent } from '../../../plugin/helpers/getPageLoadEvent';
-  import { onSelectAIOption } from '../../../plugin/globalJs/ai-dropdown.ts';
-
-  document.addEventListener(getPageLoadEvent(), () => {
-    initDropdownButton({
-      dropdownId: 'prose-ai-dropdown-button',
-      onSelect: (option: string) => onSelectAIOption(option, false),
-      onPrimaryAction: () => {
-        onSelectAIOption('claude', false);
-      },
-    });
-  });
-</script>

package/stl-docs/components/icons/chat-gpt.tsx

@@ -1,7 +1,7 @@
 export function ChatGPTIcon() {
   return (
     <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" fill="none">
-      <g clip-path="url(#clip0_2771_126147)">
+      <g clipPath="url(#clip0_2771_126147)">
         <path
           d="M14.853 6.54857C15.216 5.45907 15.091 4.26557 14.5105 3.27457C13.6375 1.75457 11.8825 0.972574 10.1685 1.34057C9.40596 0.481574 8.31046 -0.00692579 7.16196 7.42116e-05C5.40996 -0.00392579 3.85546 1.12407 3.31646 2.79107C2.19096 3.02157 1.21946 3.72607 0.650955 4.72457C-0.228545 6.24057 -0.0280446 8.15157 1.14696 9.45157C0.783955 10.5411 0.908955 11.7346 1.48946 12.7256C2.36246 14.2456 4.11746 15.0276 5.83146 14.6596C6.59346 15.5186 7.68946 16.0071 8.83796 15.9996C10.591 16.0041 12.146 14.8751 12.685 13.2066C13.8105 12.9761 14.782 12.2716 15.3505 11.2731C16.229 9.75707 16.028 7.84757 14.8535 6.54757L14.853 6.54857ZM8.83896 14.9541C8.13746 14.9551 7.45796 14.7096 6.91946 14.2601C6.94396 14.2471 6.98646 14.2236 7.01396 14.2066L10.2 12.3666C10.363 12.2741 10.463 12.1006 10.462 11.9131V7.42157L11.8085 8.19907C11.823 8.20607 11.8325 8.22007 11.8345 8.23607V11.9556C11.8325 13.6096 10.493 14.9506 8.83896 14.9541ZM2.39696 12.2026C2.04546 11.5956 1.91896 10.8841 2.03946 10.1936C2.06296 10.2076 2.10446 10.2331 2.13396 10.2501L5.31996 12.0901C5.48146 12.1846 5.68146 12.1846 5.84346 12.0901L9.73296 9.84407V11.3991C9.73396 11.4151 9.72646 11.4306 9.71396 11.4406L6.49346 13.3001C5.05896 14.1261 3.22696 13.6351 2.39746 12.2026H2.39696ZM1.55846 5.24807C1.90846 4.64007 2.46096 4.17507 3.11896 3.93357C3.11896 3.96107 3.11746 4.00957 3.11746 4.04357V7.72407C3.11646 7.91107 3.21646 8.08457 3.37896 8.17707L7.26846 10.4226L5.92196 11.2001C5.90846 11.2091 5.89146 11.2106 5.87646 11.2041L2.65546 9.34307C1.22396 8.51407 0.732955 6.68257 1.55796 5.24857L1.55846 5.24807ZM12.6215 7.82257L8.73196 5.57657L10.0785 4.79957C10.092 4.79057 10.109 4.78907 10.124 4.79557L13.345 6.65507C14.779 7.48357 15.2705 9.31807 14.442 10.7521C14.0915 11.3591 13.5395 11.8241 12.882 12.0661V8.27557C12.8835 8.08857 12.784 7.91557 12.622 7.82257H12.6215ZM13.9615 5.80557C13.938 5.79107 13.8965 5.76607 13.867 5.74907L10.681 3.90907C10.5195 3.81457 10.3195 3.81457 10.1575 3.90907L6.26796 6.15507V4.60007C6.26696 4.58407 6.27446 4.56857 6.28696 4.55857L9.50746 2.70057C10.942 1.87307 12.776 2.36557 13.603 3.80057C13.9525 4.40657 14.079 5.11607 13.9605 5.80557H13.9615ZM5.53596 8.57707L4.18896 7.79957C4.17446 7.79257 4.16496 7.77857 4.16296 7.76257V4.04307C4.16396 2.38707 5.50746 1.04507 7.16346 1.04607C7.86396 1.04607 8.54196 1.29207 9.08046 1.74007C9.05596 1.75307 9.01396 1.77657 8.98596 1.79357L5.79996 3.63357C5.63696 3.72607 5.53696 3.89907 5.53796 4.08657L5.53596 8.57607V8.57707ZM6.26746 7.00007L7.99996 5.99957L9.73246 6.99957V9.00007L7.99996 10.0001L6.26746 9.00007V7.00007Z"
           fill="var(--stl-ui-foreground)"

package/stl-docs/components/index.ts

@@ -0,0 +1,2 @@
+export * from '@stainless-api/ui-primitives';
+export * from '@stainless-api/ui-primitives/scripts';

package/stl-docs/disableCalloutSyntax.ts

@@ -0,0 +1,36 @@
+import type { AstroIntegration } from 'astro';
+import type { StarlightPlugin } from '@astrojs/starlight/types';
+
+export const disableCalloutSyntaxAstroIntegration = {
+  name: 'stl-starlight-remove-callout-syntax',
+  hooks: {
+    'astro:config:setup': ({ config: astroConfig }) => {
+      // Remove starlight callout syntax in favor of our own callout component
+      // updateConfig always deeply merges arrays so we need to mutate remarkPlugins directly
+      // in order to remove plugins that starlight added
+      astroConfig.markdown.remarkPlugins = astroConfig.markdown.remarkPlugins.filter((plugin, i, arr) => {
+        if (typeof plugin !== 'function') return true;
+        // remove:
+        // 1. remarkDirective plugin
+        if (plugin.name === 'remarkDirective') return false;
+        // 2. directly followed by remarkAsides plugin (inner function named 'attacher')
+        if (plugin.name === 'attacher') {
+          const prev = arr[i - 1];
+          if (typeof prev === 'function' && prev.name === 'remarkDirective') return false;
+        }
+        // 3. remarkDirectivesRestoration plugin
+        if (plugin.name === 'remarkDirectivesRestoration') return false;
+        return true;
+      });
+    },
+  },
+} satisfies AstroIntegration;
+
+export const disableCalloutSyntaxStarlightPlugin = {
+  name: 'stl-starlight-remove-callout-syntax',
+  hooks: {
+    'config:setup': ({ addIntegration }) => {
+      addIntegration(disableCalloutSyntaxAstroIntegration);
+    },
+  },
+} satisfies StarlightPlugin;

package/stl-docs/index.ts

@@ -1,11 +1,13 @@
 import starlight from '@astrojs/starlight';
 import react from '@astrojs/react';
+import type { StarlightPlugin } from '@astrojs/starlight/types';
 import { stainlessStarlight } from '../plugin';
+import { disableCalloutSyntaxStarlightPlugin } from './disableCalloutSyntax';
 
 import type { AstroIntegration } from 'astro';
 
 import { normalizeRedirects, type NormalizedRedirectConfig } from './redirects';
-import { join } from 'path';
+import path, { join } from 'path';
 import { mkdirSync, writeFileSync } from 'fs';
 import {
   parseStlDocsConfig,
@@ -16,11 +18,15 @@ import {
   type StarlightSidebarConfig,
 } from './loadStlDocsConfig';
 import { buildVirtualModuleString } from '../shared/virtualModule';
-
+import { resolveSrcFile } from '../resolveSrcFile';
 import geistPath from '../plugin/assets/fonts/geist/geist-latin.woff2?url';
+import { stainlessDocsMarkdownRenderer } from './proseMarkdown/proseMarkdownIntegration';
+import { setSharedLogger } from '../shared/getSharedLogger';
 
 export * from '../plugin';
 
+const COMPONENTS_FOLDER = '/stl-docs/components';
+
 function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig) {
   // We transform our tabs into a Starlight sidebar
   // This gives them all the built-in features of Starlight (eg. auto-generated entries by directory)
@@ -40,22 +46,29 @@ function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig
   }
 
   type ComponentOverrides = StarlightConfigDefined['components'];
-  const plugins = [...config.starlightCompat.plugins];
-
   const componentOverrides: ComponentOverrides = {
-    Sidebar: '@stainless-api/docs/BaseSidebar',
-    Header: '@stainless-api/docs/Header',
-    ThemeSelect: '@stainless-api/docs/ThemeSelect',
-    ContentPanel: '@stainless-api/docs/ContentPanel',
-    TableOfContents: '@stainless-api/docs/TableOfContents',
+    Sidebar: resolveSrcFile(COMPONENTS_FOLDER, './sidebars/BaseSidebar.astro'),
+    Header: resolveSrcFile(COMPONENTS_FOLDER, './Header.astro'),
+    Head: resolveSrcFile(COMPONENTS_FOLDER, './Head.astro'),
+    ThemeSelect: resolveSrcFile(COMPONENTS_FOLDER, './ThemeSelect.astro'),
+    ContentPanel: resolveSrcFile(COMPONENTS_FOLDER, './content-panel/ContentPanel.astro'),
+    TableOfContents: resolveSrcFile(COMPONENTS_FOLDER, './TableOfContents.astro'),
+    PageTitle: resolveSrcFile(COMPONENTS_FOLDER, './PageTitle.astro'),
   };
 
+  const plugins: StarlightPlugin[] = [
+    // Disable starlight callout syntax in favor of our own component
+    disableCalloutSyntaxStarlightPlugin,
+  ];
+
   if (config.apiReference !== null) {
-    componentOverrides.Sidebar = '@stainless-api/docs/SDKSelectSidebar';
-    componentOverrides.Search = '@stainless-api/docs/Search';
-    plugins.unshift(stainlessStarlight(config.apiReference));
+    plugins.push(stainlessStarlight(config.apiReference));
+    componentOverrides.Sidebar = resolveSrcFile(COMPONENTS_FOLDER, './sidebars/SDKSelectSidebar.astro');
+    componentOverrides.Search = resolveSrcFile('/plugin/components/search/Search.astro');
   }
 
+  plugins.push(...config.starlightCompat.plugins);
+
   // TODO: re-add once we figure out what to do with the client router
   // if (config.enableClientRouter) {
   //   // logger.info(`Client router is enabled`);
@@ -100,20 +113,26 @@ function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig
         },
       },
     ],
-    routeMiddleware: [...config.starlightCompat.routeMiddleware, '@stainless-api/docs/tabsMiddleware'],
-    customCss: ['@stainless-api/docs/theme', ...config.customCss],
+    routeMiddleware: [
+      ...config.starlightCompat.routeMiddleware,
+      resolveSrcFile('/stl-docs/tabsMiddleware.ts'),
+    ],
+    customCss: [resolveSrcFile('/theme.css'), ...config.customCss],
     plugins,
   });
 }
 
-function stainlessDocsIntegration(config: NormalizedStainlessDocsConfig): AstroIntegration {
+function stainlessDocsIntegration(
+  config: NormalizedStainlessDocsConfig,
+  apiReferenceBasePath: string | null,
+): AstroIntegration {
   const virtualId = `virtual:stl-docs-virtual-module`;
   // The '\0' prefix tells Vite “this is a virtual module” and prevents it from being resolved again.
   const resolvedId = `\0${virtualId}`;
   let redirects: NormalizedRedirectConfig | null = null;
 
   return {
-    name: 'stl-docs-integration',
+    name: 'stl-docs-astro',
     hooks: {
       'astro:config:setup': ({ updateConfig, command, config: astroConfig }) => {
         // // we only handle redirects for builds
@@ -144,7 +163,9 @@ function stainlessDocsIntegration(config: NormalizedStainlessDocsConfig): AstroI
                       HEADER_LINKS: config.header.links,
                       HEADER_LAYOUT: config.header.layout,
                       ENABLE_CLIENT_ROUTER: config.enableClientRouter,
-                      INCLUDE_AI_DROPDOWN_OPTIONS: config.includeAIDropdownOptions,
+                      API_REFERENCE_BASE_PATH: apiReferenceBasePath,
+                      ENABLE_PROSE_MARKDOWN_RENDERING: config.enableProseMarkdownRendering,
+                      ENABLE_CONTEXT_MENU: config.contextMenu,
                     });
                   }
                 },
@@ -171,6 +192,17 @@ function stainlessDocsIntegration(config: NormalizedStainlessDocsConfig): AstroI
   };
 }
 
+function sharedLoggerIntegration(): AstroIntegration {
+  return {
+    name: 'stainless',
+    hooks: {
+      'astro:config:setup': ({ logger }) => {
+        setSharedLogger(logger);
+      },
+    },
+  };
+}
+
 export function stainlessDocs(config: StainlessDocsUserConfig) {
   const normalizedConfigResult = parseStlDocsConfig(config);
   if (normalizedConfigResult.result === 'error') {
@@ -180,9 +212,20 @@ export function stainlessDocs(config: StainlessDocsUserConfig) {
   }
   const normalizedConfig = normalizedConfigResult.config;
 
+  // TODO: need to refactor this, but this allows us to get the base path for the API reference _if_ it exists
+  // if it doesn't exist, the value of basePath is null.
+  // the stl-starlight virtual module has base path, but it's not available when there's no API reference
+  const hasApiReference = normalizedConfig.apiReference !== null;
+  let apiReferenceBasePath: string | null = null;
+  if (hasApiReference) {
+    apiReferenceBasePath = normalizedConfig.apiReference?.basePath ?? '/api';
+  }
+
   return [
+    sharedLoggerIntegration(), // this **must** be first so it can set the shared logger used by our other integrations
     react(),
     stainlessDocsStarlightIntegration(normalizedConfig),
-    stainlessDocsIntegration(normalizedConfig),
+    stainlessDocsIntegration(normalizedConfig, apiReferenceBasePath),
+    stainlessDocsMarkdownRenderer({ enabled: normalizedConfig.enableProseMarkdownRendering }),
   ];
 }

package/stl-docs/loadStlDocsConfig.ts

@@ -45,7 +45,8 @@ type Tabs = {
   sidebar?: SidebarEntry[];
   /**
    * Whether to hide the tab in the tab bar.
-   * Defaults to `false`.
+   *
+   * Default: `false`
    */
   hidden?: boolean;
 }[];
@@ -67,7 +68,19 @@ export type StainlessDocsUserConfig = {
   experimental?: {
     starlightCompat?: ExperimentalStarlightCompatibilityConfig;
     enableClientRouter?: boolean;
+    /**
+     * Disable markdown rendering for prose content. Only disable this if it is causing issues.
+     *
+     * Default: `false`
+     */
+    disableProseMarkdownRendering?: boolean;
   };
+  /**
+   * Whether to show the context menu with options like "Copy as Markdown" and "Open in ChatGPT".
+   *
+   * Default: `true`
+   */
+  contextMenu?: boolean;
 } & PassThroughStarlightConfigOptions;
 
 type HeaderLayout = 'default' | 'stacked';
@@ -134,7 +147,9 @@ function normalizeConfig(userConfig: StainlessDocsUserConfig) {
     enableClientRouter: userConfig.experimental?.enableClientRouter ?? false,
     apiReference: userConfig.apiReference ?? null,
     sidebar: userConfig.sidebar,
-    includeAIDropdownOptions: userConfig.apiReference?.includeAIDropdownOptions ?? false,
+    enableProseMarkdownRendering:
+      userConfig.experimental?.disableProseMarkdownRendering === true ? false : true,
+    contextMenu: userConfig.contextMenu ?? true,
   };
 
   return configWithDefaults;

package/stl-docs/proseMarkdown/proseMarkdownIntegration.ts

@@ -0,0 +1,64 @@
+import type { AstroIntegration } from 'astro';
+import { readFile, writeFile } from 'fs/promises';
+import { toMarkdown } from './toMarkdown';
+import { resolveSrcFile } from '../../resolveSrcFile';
+import { getSharedLogger } from '../../shared/getSharedLogger';
+import { bold } from '../../shared/terminalUtils';
+
+export function stainlessDocsMarkdownRenderer({ enabled }: { enabled: boolean }): AstroIntegration {
+  return {
+    name: 'stl-docs-md',
+    hooks: {
+      'astro:config:setup': ({ addMiddleware }) => {
+        if (enabled) {
+          addMiddleware({
+            entrypoint: resolveSrcFile('/stl-docs/proseMarkdown/proseMarkdownMiddleware.ts'),
+            order: 'post',
+          });
+        }
+      },
+      'astro:build:done': async ({ assets, 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);
+
+        logger.info(bold(`Building ${pagesToRender.length} Markdown pages for prose content`));
+
+        const outputBasePath = dir.pathname;
+
+        let completedCount = 0;
+        for (const absHtmlPath of pagesToRender) {
+          const txt = await readFile(absHtmlPath, 'utf-8');
+          const md = await toMarkdown(txt);
+          if (md) {
+            const absMdPath = absHtmlPath.replace('.html', '.md');
+            await writeFile(absMdPath, md, 'utf-8');
+
+            completedCount++;
+
+            const relHtmlPath = absHtmlPath.replace(outputBasePath, '');
+            const relMdPath = absMdPath.replace(outputBasePath, '');
+
+            logger.info(`(${completedCount}/${pagesToRender.length}) ${relHtmlPath} -> ${relMdPath}`);
+          } else {
+            logger.error(`Failed to render ${absHtmlPath} as Markdown`);
+            process.exit(1);
+          }
+        }
+      },
+    },
+  };
+}

package/stl-docs/proseMarkdown/proseMarkdownMiddleware.ts

@@ -0,0 +1,33 @@
+import { defineMiddleware } from 'astro:middleware';
+import { toMarkdown } from './toMarkdown';
+import { API_REFERENCE_BASE_PATH } from 'virtual:stl-docs-virtual-module';
+
+// this is only run in `astro dev` for rendering prose content as Markdown on the fly.
+export const onRequest = defineMiddleware(async (context, next) => {
+  if (!import.meta.env.DEV) {
+    return next();
+  }
+
+  if (API_REFERENCE_BASE_PATH && context.url.pathname.startsWith(API_REFERENCE_BASE_PATH)) {
+    // handled by the API reference API route in stl-starlight plugin
+    return next();
+  }
+
+  if (!context.url.pathname.endsWith('/index.md')) {
+    return next();
+  }
+
+  const htmlUrl = new URL(context.url.pathname.replace('index.md', ''), context.url);
+  const resp = await fetch(htmlUrl);
+  if (!resp.ok) {
+    return new Response('Failed to fetch HTML', { status: 400 });
+  }
+  const html = await resp.text();
+  const md = await toMarkdown(html);
+
+  if (!md) {
+    return new Response('Failed to render Markdown', { status: 400 });
+  }
+
+  return new Response(md, { status: 200 });
+});