@stainless-api/docs 0.1.0-beta.98 → 1.0.0-beta.140

package/stl-docs/index.ts

@@ -6,7 +6,8 @@ import { disableCalloutSyntaxStarlightPlugin } from './disableCalloutSyntax';
 import type { AstroIntegration } from 'astro';
 
 import { normalizeRedirects, type NormalizedRedirectConfig } from './redirects';
-import { join } from 'path';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { mkdirSync, writeFileSync } from 'fs';
 import {
   parseStlDocsConfig,
@@ -17,13 +18,15 @@ import {
   type StarlightSidebarConfig,
 } from './loadStlDocsConfig';
 import { buildVirtualModuleString } from '../shared/virtualModule';
-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 { stainlessDocsVectorProseIndexing } from './proseDocSync';
 import { stainlessStarlight } from '../plugin';
 import { getFontRoles, flattenFonts } from './fonts';
+import conditionalIntegration from '../shared/conditionalIntegration';
+import { generateExamplesVirtualModule } from './aiChatExamples';
+import { ogImageStarlightPlugin } from './og-image';
 
 export * from '../plugin';
 
@@ -49,18 +52,22 @@ function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig
 
   type ComponentOverrides = StarlightConfigDefined['components'];
   const componentOverrides: ComponentOverrides = {
+    Head: resolveSrcFile(COMPONENTS_FOLDER, './Head.astro'),
+
     PageFrame: resolveSrcFile(COMPONENTS_FOLDER, './PageFrame.astro'),
+    TwoColumnContent: resolveSrcFile(COMPONENTS_FOLDER, './TwoColumnContent.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'),
+    ContentPanel: resolveSrcFile(COMPONENTS_FOLDER, './ContentPanel.astro'),
+    PageTitle: resolveSrcFile(COMPONENTS_FOLDER, './PageTitle.astro'),
+    PageSidebar: resolveSrcFile(COMPONENTS_FOLDER, './PageSidebar.astro'),
     TableOfContents: resolveSrcFile(COMPONENTS_FOLDER, './TableOfContents.astro'),
 
-    PageTitle: resolveSrcFile(COMPONENTS_FOLDER, './PageTitle.astro'),
+    Footer: resolveSrcFile(COMPONENTS_FOLDER, './Footer.astro'),
     Pagination: resolveSrcFile(COMPONENTS_FOLDER, './pagination/Pagination.astro'),
   };
 
@@ -69,7 +76,7 @@ function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig
     disableCalloutSyntaxStarlightPlugin,
   ];
 
-  if (config.apiReference !== null) {
+  if (config.apiReference) {
     plugins.push(
       stainlessStarlight({
         ...config.apiReference,
@@ -84,7 +91,11 @@ function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig
     componentOverrides.Search = resolveSrcFile('/plugin/components/search/Search.astro');
   }
 
-  plugins.push(...config.starlightCompat.plugins, ...config.plugins.map((p) => p(config)));
+  if (config.ogImage) {
+    plugins.push(ogImageStarlightPlugin(config.ogImage, config));
+  }
+
+  plugins.push(...config.starlightCompat.plugins);
 
   // TODO: re-add once we figure out what to do with the client router
   // if (config.enableClientRouter) {
@@ -98,6 +109,7 @@ function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig
 
   return starlight({
     ...config.starlightPassThrough,
+    pagefind: config.starlightCompat.pagefind,
     sidebar,
     components: {
       ...componentOverrides,
@@ -154,8 +166,6 @@ function stainlessDocsIntegration(
   config: NormalizedStainlessDocsConfig,
   apiReferenceBasePath: string | null,
 ): AstroIntegration {
-  // The '\0' prefix tells Vite “this is a virtual module” and prevents it from being resolved again.
-  const resolveVirtualModuleId = (id: string) => `\0${id}`;
   let redirects: NormalizedRedirectConfig | null = null;
 
   return {
@@ -168,43 +178,64 @@ function stainlessDocsIntegration(
           redirects = normalizeRedirects(astroConfig.redirects);
         }
 
-        const virtualModules = new Map(
-          Object.entries({
-            'virtual:stl-docs-virtual-module': buildVirtualModuleString({
-              TABS: config.tabs,
+        const base = astroConfig.base ?? '/';
+        const withBase = (link: string) =>
+          /^([a-z][a-z0-9+.-]*:|\/\/)/.test(link) ? link : path.posix.join(base, link);
+
+        let vmAiChatHandlerExport = 'export const AI_CHAT_HANDLER = undefined;';
+        if (config.aiChat?.handlerEntrypoint) {
+          const rawEntrypoint = config.aiChat.handlerEntrypoint;
+          const handlerEntrypoint = rawEntrypoint.startsWith('file://')
+            ? fileURLToPath(rawEntrypoint)
+            : path.isAbsolute(rawEntrypoint)
+              ? rawEntrypoint
+              : path.resolve(fileURLToPath(astroConfig.root), rawEntrypoint);
+          vmAiChatHandlerExport = `export { default as AI_CHAT_HANDLER } from '${handlerEntrypoint}';`;
+        }
+
+        const virtualModules = new Map<string, string>([
+          [
+            'virtual:stl-docs-virtual-module',
+            buildVirtualModuleString({
+              TABS: config.tabs.map((tab) => ({ ...tab, link: withBase(tab.link) })),
               SPLIT_TABS_ENABLED: config.splitTabsEnabled,
-              HEADER_LINKS: config.header.links,
+              HEADER_LINKS: config.header.links.map((link) => ({ ...link, link: withBase(link.link) })),
               HEADER_LAYOUT: config.header.layout,
               ENABLE_CLIENT_ROUTER: config.enableClientRouter,
               API_REFERENCE_BASE_PATH: apiReferenceBasePath ?? '/api',
               ENABLE_PROSE_MARKDOWN_RENDERING: config.enableProseMarkdownRendering,
-              ENABLE_CONTEXT_MENU: config.contextMenu, // TODO: do not duplicate this between both virtual modules
+              ENABLE_CONTEXT_MENU: !!config.contextMenu, // TODO: do not duplicate this between both virtual modules
+              CONTEXT_MENU_ENABLE_THIRD_PARTY:
+                (typeof config.contextMenu === 'object' ? config.contextMenu.thirdParty : null) ?? true,
               RENDER_PAGE_DESCRIPTIONS: config.renderPageDescriptions,
               FONTS: getFontRoles(config.fonts),
-            } 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;`
+              LINK_GROUP_TITLES_TO_OVERVIEW_PAGES: config.linkGroupTitlesToOverviewPages,
+              RENDER_CREDITS: config.credits,
+              SITE_TITLE: config.siteTitle,
+            }),
+          ],
+          ['virtual:stl-docs-ai-chat', vmAiChatHandlerExport],
+        ]);
+        if (config.aiChat) {
+          virtualModules.set(
+            'virtual:stl-docs-ai-chat-examples',
+            generateExamplesVirtualModule(config.aiChat.examples),
+          );
         }
-        export const STAINLESS_PROJECT = ${config.apiReference ? JSON.stringify(config.apiReference.stainlessProject) : 'undefined'};
-      `,
-          }),
-        );
 
         updateConfig({
-          experimental: {
-            fonts: [...flattenFonts(config.fonts), ...(astroConfig.experimental?.fonts ?? [])],
-          },
+          fonts: [...flattenFonts(config.fonts), ...(astroConfig?.fonts ?? [])],
           vite: {
+            define: {
+              __STLDOCS_HAS_API_REFERENCE__: !!config.apiReference,
+              __STLDOCS_ENABLE_AI_CHAT__: !!config.aiChat,
+            },
             plugins: [
               {
-                name: 'stl-docs-vite',
+                name: 'stl-docs-virtual-modules',
                 resolveId(id) {
-                  if (virtualModules.has(id)) return resolveVirtualModuleId(id);
+                  // The '\0' prefix tells Vite "this is a virtual module" and prevents it from being resolved again.
+                  if (virtualModules.has(id)) return `\0${id}`;
                 },
                 load(id) {
                   const bare = id.replace(/^\0/, '');
@@ -212,18 +243,6 @@ function stainlessDocsIntegration(
                 },
               },
             ],
-            optimizeDeps: {
-              include: config.aiChat
-                ? [
-                    '@stainless-api/docs-ai-chat > @stainless-api/ai-chat > lucide-react',
-                    '@stainless-api/docs-ai-chat > @stainless-api/ai-chat > motion',
-                    '@stainless-api/docs-ai-chat > @stainless-api/ai-chat > motion > framer-motion',
-                    '@stainless-api/docs-ai-chat > @stainless-api/ai-chat > react-markdown',
-                    '@stainless-api/docs-ai-chat > @stainless-api/ai-chat > react-syntax-highlighter',
-                    '@stainless-api/docs-ai-chat > @stainless-api/ai-chat > remark-gfm',
-                  ]
-                : [],
-            },
           },
           build: {
             ...astroConfig.build,
@@ -233,9 +252,9 @@ function stainlessDocsIntegration(
       },
       'astro:build:done': ({ dir }) => {
         if (redirects !== null) {
-          const stainlessDir = join(dir.pathname, '_stainless');
+          const stainlessDir = path.join(dir.pathname, '_stainless');
           mkdirSync(stainlessDir, { recursive: true });
-          const outputPath = join(stainlessDir, 'redirects.json');
+          const outputPath = path.join(stainlessDir, 'redirects.json');
           writeFileSync(outputPath, JSON.stringify(redirects, null, 2), {
             encoding: 'utf-8',
           });
@@ -256,7 +275,7 @@ function sharedLoggerIntegration(): AstroIntegration {
   };
 }
 
-export function stainlessDocs(config: StainlessDocsUserConfig): StarlightPlugin[] {
+export function stainlessDocs(config: StainlessDocsUserConfig): AstroIntegration[] {
   const normalizedConfigResult = parseStlDocsConfig(config);
   if (normalizedConfigResult.result === 'error') {
     // TODO: would be good to use the astro logger somehow
@@ -279,11 +298,15 @@ export function stainlessDocs(config: StainlessDocsUserConfig): StarlightPlugin[
     react(),
     stainlessDocsStarlightIntegration(normalizedConfig),
     stainlessDocsIntegration(normalizedConfig, apiReferenceBasePath),
-    stainlessDocsMarkdownRenderer({
-      enabled: normalizedConfig.enableProseMarkdownRendering,
-      apiReferenceBasePath,
+    conditionalIntegration({
+      condition: !config.experimental?.disableProseMarkdownRendering,
+      integration: stainlessDocsMarkdownRenderer({ apiReferenceBasePath }),
+      reason: 'disabled by experimental config "disableProseMarkdownRendering"',
+    }),
+    conditionalIntegration({
+      condition: !config.experimental?.disableStainlessProseIndexing,
+      integration: stainlessDocsVectorProseIndexing(normalizedConfig, apiReferenceBasePath),
+      reason: 'disabled by experimental config "disableStainlessProseIndexing"',
     }),
-    stainlessDocsAlgoliaProseIndexing({ apiReferenceBasePath }),
-    stainlessDocsVectorProseIndexing(normalizedConfig, apiReferenceBasePath),
   ];
 }

package/stl-docs/loadStlDocsConfig.ts

@@ -1,9 +1,11 @@
 import type { StainlessStarlightUserConfig } from '../plugin/loadPluginConfig';
-import type { StarlightPlugin, StarlightUserConfig } from '@astrojs/starlight/types';
+import type { StarlightUserConfig } from '@astrojs/starlight/types';
 import type { ButtonVariant } from '@stainless-api/ui-primitives';
 import type { AnchorHTMLAttributes } from 'react';
 import type starlight from '@astrojs/starlight';
 import { normalizeFonts, type StlDocsFontConfig } from './fonts';
+import type { ExamplePromptResponse } from './aiChatExamples';
+import type { OGImageConfig } from './og-image/config';
 
 type StarlightConfig = Parameters<typeof starlight>[0];
 
@@ -38,7 +40,7 @@ type PassThroughStarlightConfigOptions = Pick<
 
 type ExperimentalStarlightCompatibilityConfig = Pick<
   StarlightConfigDefined,
-  'components' | 'routeMiddleware' | 'plugins' | 'prerender'
+  'components' | 'routeMiddleware' | 'plugins' | 'prerender' | 'pagefind'
 >;
 
 export type Tabs = {
@@ -67,6 +69,7 @@ export type StainlessDocsUserConfig = {
     layout?: HeaderLayout;
     links?: HeaderLink[];
   };
+  disableCredits?: boolean;
   fonts?: StlDocsFontConfig;
   experimental?: {
     starlightCompat?: ExperimentalStarlightCompatibilityConfig;
@@ -77,14 +80,21 @@ export type StainlessDocsUserConfig = {
      * @default false
      */
     disableProseMarkdownRendering?: boolean;
-    aiChat?: { chatComponentPath: string };
+    disableStainlessProseIndexing?: boolean;
+    aiChat?: { handlerEntrypoint: string; examples?: ExamplePromptResponse };
+    /**
+     * Whether to link group titles to overview pages. Note: overview pages must already be present in the sidebar for this to work.
+     *
+     * @default false
+     */
+    linkGroupTitlesToOverviewPages?: boolean;
   };
   /**
    * Whether to show the context menu with options like "Copy as Markdown" and "Open in ChatGPT".
    *
    * @default true
    */
-  contextMenu?: boolean;
+  contextMenu?: boolean | { thirdParty?: boolean };
 
   /**
    * Whether to render page descriptions in prose page headers
@@ -93,10 +103,11 @@ export type StainlessDocsUserConfig = {
    */
   renderPageDescriptions?: boolean;
   /**
-   * Stainless Docs plugins.
-   * Each plugin is a function that receives the normalized config and returns a Starlight plugin.
+   * Enable and configure Open Graph image generation.
+   *
+   * Requires `takumi-js` to be installed as a dependency.
    */
-  plugins?: ((config: Exclude<NormalizedStainlessDocsConfig, 'plugins'>) => StarlightPlugin)[];
+  ogImage?: OGImageConfig;
 } & PassThroughStarlightConfigOptions;
 
 type HeaderLayout = 'default' | 'stacked';
@@ -128,6 +139,19 @@ function normalizeRouteMiddleware(userConfig: StainlessDocsUserConfig) {
   return entry;
 }
 
+function normalizeSiteTitle(userConfig: StainlessDocsUserConfig) {
+  if (typeof userConfig.title === 'string') {
+    return userConfig.title;
+  }
+  if (typeof userConfig.title === 'object') {
+    const firstValue = Object.values(userConfig.title)[0];
+    if (typeof firstValue === 'string') {
+      return firstValue;
+    }
+  }
+  throw new Error('Site title provided in config is not valid.');
+}
+
 function normalizeConfig(userConfig: StainlessDocsUserConfig) {
   const splitTabsEnabled = areSplitTabsEnabled(userConfig);
 
@@ -160,18 +184,24 @@ function normalizeConfig(userConfig: StainlessDocsUserConfig) {
     starlightCompat: {
       components: userConfig.experimental?.starlightCompat?.components ?? {},
       plugins: userConfig.experimental?.starlightCompat?.plugins ?? [],
+      pagefind: userConfig.experimental?.starlightCompat?.pagefind ?? true,
       routeMiddleware: normalizeRouteMiddleware(userConfig),
     },
     enableClientRouter: userConfig.experimental?.enableClientRouter ?? false,
     apiReference: userConfig.apiReference ?? null,
     sidebar: userConfig.sidebar,
+    enableStainlessProseIndexing:
+      userConfig.experimental?.disableStainlessProseIndexing === true ? false : true,
     enableProseMarkdownRendering:
       userConfig.experimental?.disableProseMarkdownRendering === true ? false : true,
     contextMenu: userConfig.contextMenu ?? true,
     expressiveCode: userConfig.expressiveCode,
     renderPageDescriptions: userConfig.renderPageDescriptions ?? true,
-    plugins: userConfig.plugins ?? [],
     aiChat: userConfig.experimental?.aiChat,
+    linkGroupTitlesToOverviewPages: userConfig.experimental?.linkGroupTitlesToOverviewPages ?? false,
+    credits: !userConfig.disableCredits,
+    siteTitle: normalizeSiteTitle(userConfig),
+    ogImage: userConfig.ogImage ?? null,
   };
 
   return configWithDefaults;

package/stl-docs/og-image/components/OpenGraphFunctionSignature.tsx

@@ -0,0 +1,64 @@
+import { darkThemeVars, lightThemeVars } from '../theme';
+
+export default function OpenGraphFunctionSignature({
+  params,
+  fullyQualifiedName,
+  theme,
+}: {
+  params: { ident: string; optional?: boolean }[] | undefined;
+  fullyQualifiedName: string | undefined;
+  theme?: 'light' | 'dark';
+}) {
+  if (!params || !fullyQualifiedName) {
+    return null;
+  }
+  const colors = theme === 'dark' ? darkThemeVars : lightThemeVars;
+
+  const joinedParams = params
+    .map((param) => {
+      if (param.optional) {
+        return `${param.ident}?`;
+      }
+      return param.ident;
+    })
+    .filter((p): p is string => p !== null)
+    .join(', ');
+
+  return (
+    <p
+      style={{
+        lineClamp: 1,
+        textOverflow: 'ellipsis',
+        fontSize: '33px',
+        lineHeight: '150%',
+        overflow: 'hidden',
+        width: '100%',
+        color: colors.foreground,
+        marginBottom: 0,
+        marginTop: 0,
+      }}
+    >
+      <span
+        style={{
+          color: colors.foregroundReduced,
+        }}
+      >
+        {fullyQualifiedName.split('.').slice(0, -1).join('.')}.
+      </span>
+      <span
+        style={{
+          fontWeight: 600,
+        }}
+      >
+        {fullyQualifiedName.split('.').slice(-1)}
+      </span>
+      <span
+        style={{
+          fontWeight: 600,
+        }}
+      >
+        ({joinedParams})
+      </span>
+    </p>
+  );
+}

package/stl-docs/og-image/components/OpenGraphImage.tsx

@@ -0,0 +1,126 @@
+import { darkThemeVars, lightThemeVars, typography } from '../theme';
+import { resolveLocalImageFile } from '../image-gen/get-logo-url';
+import { OG_IMAGE_OPTIONS } from 'virtual:stainless-docs/docs-og-image';
+
+/* The default open graph image template. It is expected to be used with takumi-js */
+export default function OpenGraphImage({
+  title,
+  description,
+  logo,
+  children,
+  theme,
+  breadcrumbs,
+}: {
+  title: string;
+  description?: string;
+  logo?: string;
+  children?: React.ReactNode;
+  theme?: 'light' | 'dark';
+  breadcrumbs?: string[];
+}) {
+  const colors = theme === 'dark' ? darkThemeVars : lightThemeVars;
+
+  const testLogo = OG_IMAGE_OPTIONS?.backgroundImage
+    ? resolveLocalImageFile(OG_IMAGE_OPTIONS.backgroundImage.src)
+    : undefined;
+
+  return (
+    <div
+      style={{
+        backgroundColor: colors.background,
+        width: '100%',
+        height: '100%',
+        display: 'flex',
+        alignItems: 'flex-start',
+        justifyContent: 'space-between',
+        flexDirection: 'column',
+        padding: '72px',
+        position: 'relative',
+        fontFeatureSettings: "'ss01' on, 'ss03' on, 'ss04' on, 'ss06' on",
+        lineHeight: `${typography.baseLineHeight}`,
+        fontSize: `${typography.baseFontSize}`,
+        letterSpacing: `${typography.baseLetterSpacing}`,
+      }}
+    >
+      {testLogo && (
+        <img
+          src={testLogo}
+          alt="Background"
+          style={{
+            position: 'absolute',
+            top: 0,
+            right: 0,
+            zIndex: -1,
+            ...OG_IMAGE_OPTIONS?.backgroundImage?.style,
+          }}
+        />
+      )}
+      {logo && <img src={logo} alt="Logo" style={{ height: '80px', marginBottom: '24px' }} />}
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '16px', width: '100%' }}>
+        {breadcrumbs && breadcrumbs.length > 0 && (
+          <div style={{ display: 'flex', alignItems: 'center', gap: '8px', color: colors.foregroundMuted }}>
+            {breadcrumbs.map((crumb, index) => (
+              <div key={index} style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+                {index > 0 && (
+                  <svg
+                    width="32"
+                    height="32"
+                    viewBox="0 0 32 32"
+                    fill="none"
+                    xmlns="http://www.w3.org/2000/svg"
+                  >
+                    <g opacity="0.6">
+                      <path
+                        d="M11.0573 7.05727C11.578 6.53657 12.422 6.53657 12.9427 7.05727L20.9427 15.0573C21.4634 15.578 21.4634 16.422 20.9427 16.9427L12.9427 24.9427C12.422 25.4634 11.578 25.4634 11.0573 24.9427C10.5366 24.422 10.5366 23.578 11.0573 23.0573L18.1146 16L11.0573 8.94269C10.5366 8.42199 10.5366 7.57797 11.0573 7.05727Z"
+                        fill={colors.foreground}
+                      />
+                    </g>
+                  </svg>
+                )}
+                <span
+                  style={{
+                    fontSize: `${typography.breadcrumbFontSize}`,
+                    lineHeight: `${typography.breadcrumbLineHeight}`,
+                    letterSpacing: `${typography.breadcrumbLetterSpacing}`,
+                  }}
+                >
+                  {crumb}
+                </span>
+              </div>
+            ))}
+          </div>
+        )}
+        <h1
+          style={{
+            marginBottom: '0',
+            marginTop: '0',
+            fontWeight: 600,
+            color: colors.foreground,
+            letterSpacing: `${typography.headerLetterSpacing}`,
+            lineClamp: 2,
+            textOverflow: 'ellipsis',
+            lineHeight: `${typography.headerLineHeight}`,
+            fontSize: `${typography.headerFontSize}`,
+            textWrap: 'balance',
+          }}
+        >
+          {title}
+        </h1>
+        {description && (
+          <p
+            style={{
+              color: colors.foregroundMuted,
+              marginBottom: 0,
+              marginTop: 0,
+              lineClamp: 2,
+              textOverflow: 'ellipsis',
+            }}
+          >
+            {description}
+          </p>
+        )}
+        {children}
+      </div>
+    </div>
+  );
+}

package/stl-docs/og-image/config.ts

@@ -0,0 +1,56 @@
+// Exported utilites for @stainless-api/docs consumers
+
+import type { ImageResponseOptions } from 'takumi-js/response';
+import type { CSSProperties } from 'react';
+
+export type OGImageConfig = {
+  /**
+   * Path to source file for logo to include in generated OG images
+   *
+   * example: './src/assets/og-logo.png'
+   */
+  logo?: string;
+  /**
+   * Takumi ImageResponseOptions for OG image generation
+   */
+  renderOptions?: Omit<ImageResponseOptions, 'fonts'>;
+  /**
+   * A background image for the OG images. A tailwind `tw` string can be provided to style the image.
+   *
+   * example: './src/assets/og-background-logo.png'
+   */
+  backgroundImage?: {
+    /**
+     * Path to source file for background image
+     *
+     * example: './src/assets/og-background-logo.png'
+     */
+    src: string;
+    /**
+     * Style applied to the background image using React CSSProperties
+     *
+     * example: { right: -20px }
+     */
+    style?: CSSProperties;
+  };
+  /** Preferred theme for the OG images
+   */
+  theme?: 'light' | 'dark';
+  /** The base path for the docs site. To be used when setting `base` within your astro config is not sufficient depending on hosting strategy.
+   * If your docs site is hosted at a subpath (e.g. example.com/docs), set the basePath to '/docs'.
+   *
+   * example: '/docs'
+   */
+  basePath?: string;
+  /**
+   * Override the default OG image components with custom implementations.
+   * Each value should be a file path to a component that exports a default React component.
+   *
+   * You can import the default components from `@stainless-api/docs/og-image/components/OpenGraphImage`
+   * and `@stainless-api/docs/og-image/components/OpenGraphFunctionSignature` to compose with them.
+   */
+  components?: {
+    OpenGraphImage?: string;
+    OpenGraphFunctionSignature?: string;
+  };
+};