@stainless-api/docs 0.1.0-beta.7 → 0.1.0-beta.70

package/stl-docs/components/nav-tabs/SecondaryNavTabs.astro

@@ -34,13 +34,7 @@ const navLinks = buildNavLinks(Astro.locals.starlightRoute);
       align-items: center;
       padding: 0;
       list-style: none;
-      overflow-x: auto;
       margin-bottom: -1px;
-      gap: 0.29rem;
-    }
-
-    .stl-active-secondary-link:hover {
-      background-color: transparent;
     }
 
     li {
@@ -48,7 +42,21 @@ const navLinks = buildNavLinks(Astro.locals.starlightRoute);
       border-bottom: 2px solid transparent;
 
       &.active {
-        border-color: var(--sl-color-text-accent);
+        border-color: var(--stl-color-accent-border-strong);
+      }
+
+      .stl-ui-button {
+        /* match sidebar. TODO: hoist sidebar variables to use those instead of hardcoding? */
+        border-width: 0;
+        padding: 8px 12px;
+        margin-inline: -12px;
+      }
+      /* cover for button’s negative margin */
+      &:not(:first-child) {
+        margin-inline-start: 12px;
+      }
+      &:not(:last-child) {
+        margin-inline-end: 12px;
       }
     }
   }
@@ -56,7 +64,6 @@ const navLinks = buildNavLinks(Astro.locals.starlightRoute);
   @media (min-width: 50rem) {
     .stl-secondary-nav-tabs {
       display: block;
-      padding-left: 0.55rem;
     }
   }
 </style>

package/stl-docs/components/nav-tabs/buildNavLinks.ts

@@ -1,9 +1,10 @@
 import type { StarlightRouteData } from '@astrojs/starlight/route-data';
 import { TABS } from 'virtual:stl-docs-virtual-module';
+import type { StarlightRouteWithStlDocs } from '../../tabsMiddleware';
 
 export function buildNavLinks(starlightRoute: StarlightRouteData) {
-  // TODO: specify the type of Astro.locals.starlightRoute._stlStarlight
-  const activeTabIndex = starlightRoute._stlStarlight?.activeTabIndex;
+  const routeData: StarlightRouteWithStlDocs = starlightRoute;
+  const activeTabIndex = routeData?._stlDocs?.activeTabIndex;
 
   const navLinks = TABS.map((item, index) => ({
     ...item,

package/stl-docs/components/pagination/HomeLink.astro

@@ -0,0 +1,10 @@
+---
+import { base } from 'astro:config/client';
+import { HomeIcon } from 'lucide-react';
+import PaginationLinkQuiet from './PaginationLinkQuiet.astro';
+---
+
+<PaginationLinkQuiet href={base}>
+  <HomeIcon slot="icon" />
+  Home
+</PaginationLinkQuiet>

package/stl-docs/components/pagination/Pagination.astro

@@ -0,0 +1,175 @@
+---
+import HomeLink from './HomeLink.astro';
+import PaginationLinkEmphasized from './PaginationLinkEmphasized.astro';
+
+import { getPrevNextPage } from './util';
+import config from 'virtual:starlight/user-config';
+const { prev, next } = (await getPrevNextPage(Astro.locals.starlightRoute, config.pagination)) ?? {};
+---
+
+{
+  next || prev ? (
+    <div class="pagination-links print:hidden stl-ui-not-prose">
+      {/* Previous */}
+      {!prev && <HomeLink />}
+      {/* TODO: intelligently decide whether or not to emphasize the previous page - including user config option (page level?) */}
+      {/* {prev && next && (
+        <PaginationLinkQuiet href={prev.href}>
+          <ChevronLeftIcon slot="icon" />
+          Previous
+        </PaginationLinkQuiet>
+      )} */}
+      {prev && (
+        <PaginationLinkEmphasized href={prev.href} direction="prev">
+          <h2 slot="page-title">{prev.label}</h2>
+          {prev.description && <p slot="page-description">{prev.description}</p>}
+        </PaginationLinkEmphasized>
+      )}
+
+      {/* Next */}
+      {!next && <HomeLink />}
+      {next && (
+        <PaginationLinkEmphasized href={next.href} direction="next">
+          <h2 slot="page-title">{next.label}</h2>
+          {next.description && <p slot="page-description">{next.description}</p>}
+        </PaginationLinkEmphasized>
+      )}
+    </div>
+  ) : null
+}
+
+<style is:global>
+  @layer starlight.core {
+    .pagination-links,
+    .pagination-links a,
+    .pagination-links a:hover,
+    .pagination-links a[rel='next'],
+    .link-title {
+      all: revert-layer;
+    }
+  }
+
+  .pagination-links {
+    --stl-ui-pagination-padding: 8px;
+    --stl-ui-pagination-border-radius-inner: var(--stl-ui-layout-border-radius-sml);
+
+    padding: var(--stl-ui-pagination-padding);
+    background-color: var(--stl-color-faint-background);
+    border: 1px solid var(--stl-color-border);
+    border-radius: calc(var(--stl-ui-pagination-border-radius-inner) + var(--stl-ui-pagination-padding));
+
+    font-size: var(--stl-typography-scale-sm);
+    letter-spacing: normal;
+
+    display: flex;
+    gap: 8px;
+
+    margin-bottom: 2rem;
+    color: inherit; /* stl-ui-not-prose sets color: initial */
+
+    a {
+      border-radius: var(--stl-ui-pagination-border-radius-inner);
+    }
+  }
+
+  .pagination-links__link {
+    display: flex;
+    border-radius: var(--stl-ui-pagination-border-radius-inner);
+    padding: 8px 12px;
+    display: flex;
+    text-decoration: none;
+    align-items: center;
+    color: inherit;
+  }
+
+  .pagination-links__link--emphasized {
+    background-color: var(--stl-color-background);
+    border: 1px solid var(--stl-color-border);
+    flex: 1 1 50%;
+    gap: 12px;
+  }
+
+  .pagination-links__link--quiet {
+    flex: 0 1 auto;
+  }
+
+  .pagination-links__button {
+    display: flex;
+    align-items: center;
+    padding: 8px 14px;
+    font-weight: 500;
+    line-height: 1;
+
+    svg {
+      width: 16px;
+      height: 16px;
+      margin-block: -4px;
+      margin-inline-start: -6px;
+      margin-inline-end: 6px;
+    }
+
+    &.pagination-links__link--quiet {
+      padding-inline: 22px;
+    }
+  }
+
+  .pagination-links__link__divider {
+    border: 0;
+    border-inline-start: 1px solid var(--stl-color-border);
+    align-self: stretch;
+  }
+
+  .pagination-links__page-description {
+    padding-block: 4px;
+    padding-inline-start: 8px;
+    padding-inline-end: 2px;
+    line-height: 1.5;
+    flex: 1 1 50%;
+    width: 0;
+
+    h2,
+    p {
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+    h2 {
+      font-size: inherit;
+      font-weight: 500;
+    }
+    p {
+      font-size: var(--stl-typography-scale-xs);
+      color: var(--stl-color-foreground-muted);
+    }
+  }
+  .pagination-links__link--quiet:hover {
+    background-color: var(--stl-color-background-hover);
+  }
+  .pagination-links__link--emphasized:hover {
+    border-color: var(--stl-color-border-strong);
+    .pagination-links__page-description h2 {
+      text-decoration: underline;
+      text-decoration-color: var(--stl-color-foreground-reduced);
+    }
+  }
+
+  /* “next” link runs the opposite direction of the “previous” link */
+  .pagination-links__link:last-child {
+    flex-direction: row-reverse;
+
+    &.pagination-links__button,
+    .pagination-links__button {
+      flex-direction: row-reverse;
+      svg {
+        margin-inline-start: 6px;
+        margin-inline-end: -6px;
+      }
+    }
+
+    .pagination-links__page-description {
+      padding-inline-start: 2px;
+      padding-inline-end: 8px;
+      text-align: right;
+    }
+  }
+</style>

package/stl-docs/components/pagination/PaginationLinkEmphasized.astro

@@ -0,0 +1,22 @@
+---
+import { ChevronLeftIcon, ChevronRightIcon } from 'lucide-react';
+const { href, direction } = Astro.props;
+export interface Props {
+  href: string;
+  direction: 'prev' | 'next';
+}
+---
+
+<a href={href} class="pagination-links__link pagination-links__link--emphasized">
+  <div class="pagination-links__button">
+    {{ prev: <ChevronLeftIcon />, next: <ChevronRightIcon /> }[direction]}
+    <span>{{ prev: 'Previous', next: 'Next' }[direction]}</span>
+  </div>
+
+  <hr class="pagination-links__link__divider" />
+
+  <article class="pagination-links__page-description">
+    <slot name="page-title" />
+    <slot name="page-description" />
+  </article>
+</a>

package/stl-docs/components/pagination/PaginationLinkQuiet.astro

@@ -0,0 +1,13 @@
+---
+const { href } = Astro.props;
+export interface Props {
+  href: string;
+}
+---
+
+<a href={href} class="pagination-links__link pagination-links__button pagination-links__link--quiet">
+  <slot name="icon" />
+  <span>
+    <slot />
+  </span>
+</a>

package/stl-docs/components/pagination/util.ts

@@ -0,0 +1,71 @@
+import type { StarlightRouteData } from '@astrojs/starlight/route-data';
+import { getCollection } from 'astro:content';
+
+export type SidebarEntry = StarlightRouteData['sidebar'][number];
+export type SidebarLink = Extract<SidebarEntry, { type: 'link' }>;
+export type SidebarGroup = Extract<SidebarEntry, { type: 'group' }>;
+
+export const flattenSidebar = (sidebar: SidebarEntry[]): SidebarLink[] =>
+  sidebar.flatMap((e) => (e.type === 'group' ? flattenSidebar(e.entries) : e));
+
+function findParentOfSidebarEntry(sidebar: SidebarEntry[], targetEntry: SidebarEntry): SidebarGroup | null {
+  for (const entry of sidebar) {
+    if (entry.type === 'group') {
+      if (entry.entries.includes(targetEntry)) {
+        return entry;
+      }
+      const foundInChild = findParentOfSidebarEntry(entry.entries, targetEntry);
+      if (foundInChild) {
+        return foundInChild;
+      }
+    }
+  }
+  return null;
+}
+
+export async function getPrevNextPage(page: StarlightRouteData, paginationEnabled: boolean) {
+  // TODO: respect user `next` / `prev` config from frontmatter the way starlight does
+
+  if (!paginationEnabled) return null;
+
+  const docsContent = await getCollection('docs');
+  const findSidebarLinkInContent = (link: SidebarLink) =>
+    docsContent.find((doc) => {
+      if (doc.id === 'index' && link.href === '/') return true;
+      return doc.id === link.href.replace(/^\//, '').replace(/\/$/, '');
+    });
+
+  const currentSidebar = page.sidebar;
+
+  const paginationSequence: (SidebarLink & { description?: string })[] = flattenSidebar(currentSidebar)
+    // Remove injected stl-mobile-only-sidebar-item links - TODO: better solution for this
+    .filter((link) => !(link.attrs.class ?? '').trim().split(/\s+/).includes('stl-mobile-only-sidebar-item'))
+    // Remove data-stldocs-method links from pagination sequence
+    .filter((link) => !link.attrs['data-stldocs-method'])
+    // Map data-stldocs-overview=readme links so that their name is not just “Overview”
+    .map((link) => {
+      if (link.attrs['data-stldocs-overview'] && link.label === 'Overview') {
+        const parent = findParentOfSidebarEntry(currentSidebar, link);
+        if (parent) return { ...link, label: parent.label };
+      }
+      return link;
+    })
+    .map((link) => {
+      const contentEntry = findSidebarLinkInContent(link);
+      if (contentEntry) return { ...link, description: contentEntry.data.description };
+      return link;
+    });
+
+  const currentIndex = paginationSequence.findIndex((e) => e.isCurrent);
+  if (currentIndex === -1) return null;
+
+  const prevIndex = currentIndex > 0 ? currentIndex - 1 : null;
+  const nextIndex = currentIndex < paginationSequence.length - 1 ? currentIndex + 1 : null;
+  const prevSidebarEntry = prevIndex !== null ? (paginationSequence[prevIndex] ?? null) : null;
+  const nextSidebarEntry = nextIndex !== null ? (paginationSequence[nextIndex] ?? null) : null;
+
+  return {
+    prev: prevSidebarEntry,
+    next: nextSidebarEntry,
+  };
+}

package/stl-docs/components/scripts.ts

@@ -0,0 +1 @@
+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,6 +1,7 @@
 import starlight from '@astrojs/starlight';
 import react from '@astrojs/react';
-import { stainlessStarlight } from '../plugin';
+import type { StarlightPlugin } from '@astrojs/starlight/types';
+import { disableCalloutSyntaxStarlightPlugin } from './disableCalloutSyntax';
 
 import type { AstroIntegration } from 'astro';
 
@@ -16,11 +17,17 @@ import {
   type StarlightSidebarConfig,
 } from './loadStlDocsConfig';
 import { buildVirtualModuleString } from '../shared/virtualModule';
-
-import geistPath from '../plugin/assets/fonts/geist/geist-latin.woff2?url';
+import type * as StlDocsVirtualModule from 'virtual:stl-docs-virtual-module';
+import { resolveSrcFile } from '../resolveSrcFile';
+import { stainlessDocsMarkdownRenderer } from './proseMarkdown/proseMarkdownIntegration';
+import { setSharedLogger } from '../shared/getSharedLogger';
+import { stainlessDocsAlgoliaProseIndexing, stainlessDocsVectorProseIndexing } from './proseSearchIndexing';
+import { stainlessStarlight } from '../plugin';
 
 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,21 +47,40 @@ 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',
+    PageFrame: resolveSrcFile(COMPONENTS_FOLDER, './PageFrame.astro'),
+
+    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'),
+    ContentPanel: resolveSrcFile(COMPONENTS_FOLDER, './content-panel/ContentPanel.astro'),
+    TableOfContents: resolveSrcFile(COMPONENTS_FOLDER, './TableOfContents.astro'),
+
+    PageTitle: resolveSrcFile(COMPONENTS_FOLDER, './PageTitle.astro'),
+    Pagination: resolveSrcFile(COMPONENTS_FOLDER, './pagination/Pagination.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,
+        contextMenu: config.contextMenu,
+      }),
+    );
+    componentOverrides.Sidebar = resolveSrcFile(COMPONENTS_FOLDER, './sidebars/SDKSelectSidebar.astro');
+    componentOverrides.Search = resolveSrcFile('/plugin/components/search/Search.astro');
   }
 
+  plugins.push(...config.starlightCompat.plugins, ...config.plugins.map((p) => p(config)));
+
   // TODO: re-add once we figure out what to do with the client router
   // if (config.enableClientRouter) {
   //   // logger.info(`Client router is enabled`);
@@ -63,6 +89,8 @@ function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig
   //   // logger.info(`Client router is disabled`);
   // }
 
+  const userExpressiveCode = typeof config.expressiveCode === 'object' ? config.expressiveCode : {};
+
   return starlight({
     ...config.starlightPassThrough,
     sidebar,
@@ -86,68 +114,104 @@ function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig
         setupNavLinksInitial();
       `,
       },
-      // TODO: for users who are overriding the font stack in their own styles, how can we know that
-      // and preload their font instead of ours?
-      {
-        tag: 'link',
-        attrs: {
-          rel: 'preload',
-          as: 'font',
-          type: 'font/woff2',
-          crossorigin: 'anonymous',
-          href: geistPath,
+    ],
+    routeMiddleware: [
+      ...config.starlightCompat.routeMiddleware,
+      resolveSrcFile('/stl-docs/tabsMiddleware.ts'),
+    ],
+    customCss: [resolveSrcFile('/theme.css'), ...config.customCss],
+
+    expressiveCode: {
+      ...userExpressiveCode,
+      themes: userExpressiveCode.themes ?? ['github-light', 'github-dark'],
+      styleOverrides: {
+        ...userExpressiveCode.styleOverrides,
+        textMarkers: {
+          insBackground: 'var(--stl-color-green-muted-background)',
+          insBorderColor: 'var(--stl-color-green-border)',
+          insDiffIndicatorColor: 'var(--stl-color-green-foreground-reduced)',
+
+          delBackground: 'var(--stl-color-red-muted-background)',
+          delBorderColor: 'var(--stl-color-red-border)',
+          delDiffIndicatorColor: 'var(--stl-color-red-foreground-reduced)',
+
+          markBackground: 'var(--stl-color-blue-muted-background)',
+          markBorderColor: 'var(--stl-color-blue-border)',
+          ...userExpressiveCode.styleOverrides?.textMarkers,
         },
       },
-    ],
-    routeMiddleware: [...config.starlightCompat.routeMiddleware, '@stainless-api/docs/tabsMiddleware'],
-    customCss: ['@stainless-api/docs/theme', ...config.customCss],
+    },
     plugins,
   });
 }
 
-function stainlessDocsIntegration(config: NormalizedStainlessDocsConfig): AstroIntegration {
-  const virtualId = `virtual:stl-docs-virtual-module`;
+function stainlessDocsIntegration(
+  config: NormalizedStainlessDocsConfig,
+  apiReferenceBasePath: string | null,
+): AstroIntegration {
+  const virtualModules = new Map(
+    Object.entries({
+      'virtual:stl-docs-virtual-module': buildVirtualModuleString({
+        TABS: config.tabs,
+        SPLIT_TABS_ENABLED: config.splitTabsEnabled,
+        HEADER_LINKS: config.header.links,
+        HEADER_LAYOUT: config.header.layout,
+        ENABLE_CLIENT_ROUTER: config.enableClientRouter,
+        API_REFERENCE_BASE_PATH: apiReferenceBasePath,
+        ENABLE_PROSE_MARKDOWN_RENDERING: config.enableProseMarkdownRendering,
+        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;`
+        }
+        export const STAINLESS_PROJECT = ${config.apiReference ? JSON.stringify(config.apiReference.stainlessProject) : 'undefined'};
+      `,
+    }),
+  );
+
   // The '\0' prefix tells Vite “this is a virtual module” and prevents it from being resolved again.
-  const resolvedId = `\0${virtualId}`;
+  const resolveVirtualModuleId = (id: string) => `\0${id}`;
   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
-        // // in dev, Astro handles them for us
+        // we only handle redirects for builds
+        // in dev, Astro handles them for us
         if (command === 'build' && astroConfig.redirects) {
           redirects = normalizeRedirects(astroConfig.redirects);
         }
 
         updateConfig({
           vite: {
-            ssr: {
-              noExternal: ['@stainless-api/ui-primitives'],
-            },
-            optimizeDeps: { include: ['@stainless-api/ui-primitives'] },
             plugins: [
               {
                 name: 'stl-docs-vite',
                 resolveId(id) {
-                  if (id === virtualId) {
-                    return resolvedId;
-                  }
+                  if (virtualModules.has(id)) return resolveVirtualModuleId(id);
                 },
                 load(id) {
-                  if (id === resolvedId) {
-                    return buildVirtualModuleString({
-                      TABS: config.tabs,
-                      SPLIT_TABS_ENABLED: config.splitTabsEnabled,
-                      HEADER_LINKS: config.header.links,
-                      HEADER_LAYOUT: config.header.layout,
-                      ENABLE_CLIENT_ROUTER: config.enableClientRouter,
-                    });
-                  }
+                  const bare = id.replace(/^\0/, '');
+                  if (virtualModules.has(bare)) return virtualModules.get(bare);
                 },
               },
             ],
+            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,
@@ -158,7 +222,7 @@ function stainlessDocsIntegration(config: NormalizedStainlessDocsConfig): AstroI
       'astro:build:done': ({ dir }) => {
         if (redirects !== null) {
           const stainlessDir = join(dir.pathname, '_stainless');
-          mkdirSync(stainlessDir);
+          mkdirSync(stainlessDir, { recursive: true });
           const outputPath = join(stainlessDir, 'redirects.json');
           writeFileSync(outputPath, JSON.stringify(redirects, null, 2), {
             encoding: 'utf-8',
@@ -169,7 +233,18 @@ function stainlessDocsIntegration(config: NormalizedStainlessDocsConfig): AstroI
   };
 }
 
-export function stainlessDocs(config: StainlessDocsUserConfig) {
+function sharedLoggerIntegration(): AstroIntegration {
+  return {
+    name: 'stainless',
+    hooks: {
+      'astro:config:setup': ({ logger }) => {
+        setSharedLogger(logger);
+      },
+    },
+  };
+}
+
+export function stainlessDocs(config: StainlessDocsUserConfig): StarlightPlugin[] {
   const normalizedConfigResult = parseStlDocsConfig(config);
   if (normalizedConfigResult.result === 'error') {
     // TODO: would be good to use the astro logger somehow
@@ -178,9 +253,25 @@ 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,
+      apiReferenceBasePath,
+    }),
+    stainlessDocsAlgoliaProseIndexing({ apiReferenceBasePath }),
+    stainlessDocsVectorProseIndexing(normalizedConfig, apiReferenceBasePath),
   ];
 }