@stainless-api/docs 0.1.0-beta.35 → 0.1.0-beta.37

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @stainless-api/docs
 
+## 0.1.0-beta.37
+
+### Patch Changes
+
+- 5f14e53: Render page descriptions as part of page header by default
+- Updated dependencies [49e1b93]
+  - @stainless-api/docs-ui@0.1.0-beta.30
+  - @stainless-api/ui-primitives@0.1.0-beta.23
+
+## 0.1.0-beta.36
+
+### Patch Changes
+
+- Updated dependencies [7897575]
+  - @stainless-api/ui-primitives@0.1.0-beta.22
+  - @stainless-api/docs-ui@0.1.0-beta.29
+
 ## 0.1.0-beta.35
 
 ### Patch Changes

package/components/variables.css

@@ -11,6 +11,7 @@
   --stldocs-color-gray-6: var(--sl-color-gray-6);
   --stldocs-color-gray-7: var(--sl-color-gray-7);
   --stldocs-color-gray-8: var(--sl-color-gray-8);
+  --stldocs-color-gray-9: var(--sl-color-gray-9);
 
   --stldocs-color-accent-low: var(--sl-color-accent-low);
   --stldocs-color-accent-high: var(--sl-color-accent-high);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.35",
+  "version": "0.1.0-beta.37",
   "publishConfig": {
     "access": "public"
   },
@@ -32,40 +32,40 @@
   },
   "dependencies": {
     "@astrojs/markdown-remark": "^6.3.2",
-    "@astrojs/react": "^4.4.1",
+    "@astrojs/react": "^4.4.2",
     "@stainless-api/sdk": "0.1.0-alpha.12",
     "cheerio": "^1.1.2",
     "clsx": "^2.1.1",
     "dotenv": "17.2.3",
     "get-port": "^7.1.0",
     "highlight.js": "^11.11.1",
-    "lucide-react": "^0.544.0",
+    "lucide-react": "^0.553.0",
     "marked": "^16.0.0",
-    "remark-github-alerts": "^0.1.1",
-    "shiki": "^3.9.2",
-    "web-worker": "^1.5.0",
-    "yaml": "^2.8.0",
     "node-html-parser": "^7.0.1",
     "rehype-parse": "^9.0.1",
     "rehype-remark": "^10.0.1",
     "remark-gfm": "^4.0.1",
+    "remark-github-alerts": "^0.1.1",
     "remark-stringify": "^11.0.0",
+    "shiki": "^3.9.2",
     "unified": "^11.0.5",
-    "@stainless-api/ui-primitives": "0.1.0-beta.21",
-    "@stainless-api/docs-ui": "0.1.0-beta.28"
+    "web-worker": "^1.5.0",
+    "yaml": "^2.8.0",
+    "@stainless-api/ui-primitives": "0.1.0-beta.23",
+    "@stainless-api/docs-ui": "0.1.0-beta.30"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.5",
     "@markdoc/markdoc": "^0.5.2",
-    "@types/node": "^24.4.0",
-    "@types/react": "^19.2.2",
-    "@types/react-dom": "^19.2.2",
+    "@types/node": "24.5.1",
+    "@types/react": "^19.2.4",
+    "@types/react-dom": "^19.2.3",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "tsx": "^4.20.3",
     "typescript": "5.9.3",
     "vite": "^6.3.6",
-    "zod": "^4.0.0",
+    "zod": "^4.1.12",
     "@stainless/sdk-json": "^0.1.0-beta.0",
     "@stainless/eslint-config": "0.1.0-beta.0"
   },

package/plugin/buildAlgoliaIndex.ts

@@ -2,8 +2,8 @@ import Markdoc from '@markdoc/markdoc';
 import Stainless from '@stainless-api/sdk';
 import { createSDKJSON, parseInputs, transformOAS } from './cms/worker';
 import type * as SDKJSON from '@stainless/sdk-json';
-import { Languages } from '@stainless-api/docs-ui/src/routing';
-import { buildIndex } from '@stainless-api/docs-ui/src/search/providers/algolia';
+import { Languages } from '@stainless-api/docs-ui/routing';
+import { buildIndex } from '@stainless-api/docs-ui/search/providers/algolia';
 import type { VersionUserConfig } from './loadPluginConfig';
 import type { AstroIntegrationLogger } from 'astro';
 

package/plugin/cms/server.ts

@@ -4,7 +4,7 @@ import { readFile } from 'fs/promises';
 
 import type * as SDKJSON from '@stainless/sdk-json';
 import { createSDKJSON, parseInputs, transformOAS } from './worker';
-import { Languages, parseRoute, type DocsLanguage } from '@stainless-api/docs-ui/src/routing';
+import { Languages, parseRoute, type DocsLanguage } from '@stainless-api/docs-ui/routing';
 import Stainless, { APIError } from '@stainless-api/sdk';
 
 import {

package/plugin/cms/sidebar-builder.ts

@@ -1,5 +1,5 @@
 import type * as SDKJSON from '@stainless/sdk-json';
-import { generateRoute, walkTree, type DocsLanguage } from '@stainless-api/docs-ui/src/routing';
+import { generateRoute, walkTree, type DocsLanguage } from '@stainless-api/docs-ui/routing';
 import type { StarlightRouteData } from '@astrojs/starlight/route-data';
 
 function isResourceNonEmpty(resource: SDKJSON.Resource) {

package/plugin/cms/worker.ts

@@ -1,5 +1,5 @@
 import Worker from 'web-worker';
-import { Languages, type DocsLanguage } from '@stainless-api/docs-ui/src/routing';
+import { Languages, type DocsLanguage } from '@stainless-api/docs-ui/routing';
 import type * as SDKJSON from '@stainless/sdk-json';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';

package/plugin/components/SDKSelect.astro

@@ -1,6 +1,6 @@
 ---
-import type { DocsLanguage } from '@stainless-api/docs-ui/src/routing';
-import { parseRoute } from '@stainless-api/docs-ui/src/routing';
+import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
+import { parseRoute } from '@stainless-api/docs-ui/routing';
 import { cmsClient } from '../cms/client';
 import { BASE_PATH, DEFAULT_LANGUAGE, EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
 import { Languages } from '../languages';

package/plugin/components/SnippetCode.tsx

@@ -2,13 +2,14 @@ import type {
   SnippetCodeProps,
   SnippetContainerProps,
   SnippetRequestContainerProps,
-} from '@stainless-api/docs-ui/src/components';
-import { useHighlight, useLanguage } from '@stainless-api/docs-ui/src/contexts';
-import style from '@stainless-api/docs-ui/src/style';
+} from '@stainless-api/docs-ui/components';
+import { useHighlight, useLanguage } from '@stainless-api/docs-ui/contexts';
+import style from '@stainless-api/docs-ui/style';
 import * as cheerio from 'cheerio/slim';
 import { EXPERIMENTAL_COLLAPSIBLE_SNIPPETS } from 'virtual:stl-starlight-virtual-module';
 import clsx from 'clsx';
 import { Button } from '@stainless-api/ui-primitives';
+
 /*
  * This may be replaced by additional data from the sdk.
  * Without information from the sdk, we use simple heuristics per language.

package/plugin/components/search/SearchIsland.tsx

@@ -1,8 +1,8 @@
 import * as React from 'react';
 import { BASE_PATH, HIGHLIGHT_THEMES, SEARCH } from 'virtual:stl-starlight-virtual-module';
-import { parseRoute, generateRoute } from '@stainless-api/docs-ui/src/routing';
-import { SearchModal } from '@stainless-api/docs-ui/src/search/index';
-import { ChatModal } from '@stainless-api/docs-ui/src/components/chat';
+import { parseRoute, generateRoute } from '@stainless-api/docs-ui/routing';
+import { SearchModal } from '@stainless-api/docs-ui/search';
+import { ChatModal } from '@stainless-api/docs-ui/components/chat';
 import * as Markdoc from '@markdoc/markdoc';
 import { createHighlighter } from 'shiki';
 import type { BundledLanguage, BundledTheme, HighlighterGeneric } from 'shiki';
@@ -13,9 +13,9 @@ import {
   MarkdownProvider,
   NavigationProvider,
   SearchProvider,
-} from '@stainless-api/docs-ui/src/contexts';
-import { ComponentProvider } from '@stainless-api/docs-ui/src/contexts/component';
-import type { SearchSettings } from '@stainless-api/docs-ui/src/search/types';
+} from '@stainless-api/docs-ui/contexts';
+import { ComponentProvider } from '@stainless-api/docs-ui/contexts/component';
+import type { SearchSettings } from '@stainless-api/docs-ui/search/types';
 
 let $$highlighter: HighlighterGeneric<BundledLanguage, BundledTheme> | null = null;
 async function getHighlighter() {

package/plugin/generateAPIReferenceLink.ts

@@ -2,7 +2,7 @@
 
 import type { StarlightRouteData } from '@astrojs/starlight/route-data';
 import type * as SDKJSON from '@stainless/sdk-json';
-import { walkTree } from '@stainless-api/docs-ui/src/routing';
+import { walkTree } from '@stainless-api/docs-ui/routing';
 
 const INTERNAL_REFERENCE_ENTRY_MARKER = 'STL_STARLIGHT_API_REFERENCE_METHOD_LINK_PLACEHOLDER';
 

package/plugin/globalJs/navigation.ts

@@ -1,4 +1,4 @@
-import { parseRoute, scrollToPath } from '@stainless-api/docs-ui/src/routing';
+import { parseRoute, scrollToPath } from '@stainless-api/docs-ui/routing';
 import { BASE_PATH } from 'virtual:stl-starlight-virtual-module';
 import { updateSelectedLanguage } from '../languages';
 import { navigate } from 'astro:transitions/client';

package/plugin/index.ts

@@ -21,6 +21,7 @@ import {
   type SpecRetrieverConfig,
 } from './loadPluginConfig';
 import { buildVirtualModuleString } from '../shared/virtualModule';
+import type * as StlStarlightVirtualModule from 'virtual:stl-starlight-virtual-module';
 import path from 'path';
 import fs from 'fs';
 import { getSharedLogger } from '../shared/getSharedLogger';
@@ -225,7 +226,7 @@ async function stlStarlightAstroIntegration(
                         PROPERTY_SETTINGS: pluginConfig.propertySettings,
                         SEARCH: pluginConfig.search,
                         ENABLE_CONTEXT_MENU: pluginConfig.contextMenu,
-                      }),
+                      } satisfies Omit<typeof StlStarlightVirtualModule, 'MIDDLEWARE'>),
                       vmMiddlewareExport,
                     ].join('\n');
                   }
@@ -334,5 +335,5 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
 }
 
 // Additional exports we want for Stainless <-> docs integration.
-export { parseStainlessPath } from '@stainless-api/docs-ui/src/routing';
-export { renderMarkdown } from '@stainless-api/docs-ui/src/markdown';
+export { parseStainlessPath } from '@stainless-api/docs-ui/routing';
+export { renderMarkdown } from '@stainless-api/docs-ui/markdown';

package/plugin/languages.ts

@@ -1,4 +1,4 @@
-import type { DocsLanguage } from '@stainless-api/docs-ui/src/routing';
+import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
 import KotlinIcon from './assets/languages/kotlin.svg';
 import RubyIcon from './assets/languages/ruby.svg';
 import TerraformIcon from './assets/languages/terraform.svg';

package/plugin/loadPluginConfig.ts

@@ -3,8 +3,8 @@ import { homedir } from 'os';
 import { existsSync, readFileSync } from 'fs';
 
 import type { CreateShikiHighlighterOptions } from '@astrojs/markdown-remark';
-import type { DocsLanguage } from '@stainless-api/docs-ui/src/routing';
-import type { PropertySettingsType } from '@stainless-api/docs-ui/src/contexts';
+import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
+import type { PropertySettingsType } from '@stainless-api/docs-ui/contexts';
 import type { InputFilePaths } from '../plugin/cms/server';
 import { bold } from '../shared/terminalUtils';
 
@@ -50,8 +50,8 @@ export type StainlessStarlightUserConfig = {
 
   /**
    * Optional mount point for API reference docs.
-   * Default: `/api`
    * Example: `/my-api` → docs available at `/my-api/…`.
+   * @default `/api`
    */
   basePath?: string;
 
@@ -63,8 +63,8 @@ export type StainlessStarlightUserConfig = {
 
   /**
    * Optional language to treat as the default when the user hasn't selected one.
-   * Default: `"http"`
-   * Example: `"python"`
+   * Example: `'python'`
+   * @default 'http'
    */
   defaultLanguage?: DocsLanguage;
 
@@ -98,7 +98,7 @@ export type StainlessStarlightUserConfig = {
   contentPanel?: {
     /**
      * Optional layout for the content panel.
-     * Default: `"double-pane"`
+     * @default 'double-pane'
      */
     layout?: ContentLayout;
   };
@@ -116,7 +116,7 @@ export type StainlessStarlightUserConfig = {
      * When set to `true`, the enableAISearch` setting turns on support for
      * LLM-based conversations with the API documentation
      *
-     * Default: `false`
+     * @default false
      */
     enableAISearch?: boolean;
   };
@@ -125,14 +125,14 @@ export type StainlessStarlightUserConfig = {
    * Enable experimental collapsible code snippets. Snippets will be collapsed by default for
    * single-pane and mobile layouts.
    *
-   * Default: `false`
+   * @default false
    */
   experimentalCollapsibleSnippets?: boolean;
 
   /**
    * Whether to show the context menu with options like "Copy as Markdown" and "Open in ChatGPT".
    *
-   * Default: `true`
+   * @default true
    */
   contextMenu?: boolean;
 };
@@ -336,11 +336,11 @@ function normalizeConfig(partial: SomeStainlessStarlightUserConfig, command: Ast
 export type NormalizedStainlessStarlightConfig = ReturnType<typeof normalizeConfig>;
 
 /*
- The goal of the code in this file is to take a user's config and normalize it. 
+ The goal of the code in this file is to take a user's config and normalize it.
  Specifically: we want a single complete config format used throughout the internals of the plugin.
 
  We've tried to avoid any config values being optional/undefined. To accomplish this:
- - Any optional config values should have their defaults set here: eg. basePath defaults to /api 
+ - Any optional config values should have their defaults set here: eg. basePath defaults to /api
  - If a field is only used in certain contexts, we make each context a discriminated union (see SpecRetrieverConfig)
  - We prefer empty arrays over undefined/null
 */

package/plugin/middlewareBuilder/stainlessMiddleware.d.ts

@@ -1,4 +1,4 @@
-import type { TransformRequestSnippetFn } from '@stainless-api/docs-ui/src/components/sdk';
+import type { TransformRequestSnippetFn } from '@stainless-api/docs-ui/components/sdk';
 
 export type StlStarlightMiddleware = {
   transformRequestSnippet?: TransformRequestSnippetFn;

package/plugin/react/Routing.tsx

@@ -7,7 +7,7 @@ import remarkGfmAlerts from 'remark-github-alerts';
 import type { MarkdownHeading } from 'astro';
 import type { StarlightRouteData } from '@astrojs/starlight/route-data';
 import type * as SDKJSON from '@stainless/sdk-json';
-import { LanguageNames, type DocsLanguage } from '@stainless-api/docs-ui/src/routing';
+import { LanguageNames, type DocsLanguage } from '@stainless-api/docs-ui/routing';
 
 import {
   generateRouteList,
@@ -16,7 +16,7 @@ import {
   walkTree,
   SupportedLanguageSyntaxes,
   getLanguageSnippet,
-} from '@stainless-api/docs-ui/src/routing';
+} from '@stainless-api/docs-ui/routing';
 
 import {
   DocsProvider,
@@ -24,9 +24,9 @@ import {
   NavigationProvider,
   useSpec,
   type ContentPanelLayout,
-} from '@stainless-api/docs-ui/src/contexts';
+} from '@stainless-api/docs-ui/contexts';
 
-import { flatResources, getResourceFromSpec } from '@stainless-api/docs-ui/src/utils';
+import { flatResources, getResourceFromSpec } from '@stainless-api/docs-ui/utils';
 
 import {
   SDKMethod,
@@ -36,7 +36,7 @@ import {
   SDKIcon,
   SDKOverview,
   SDKLanguageBlock,
-} from '@stainless-api/docs-ui/src/components';
+} from '@stainless-api/docs-ui/components';
 
 import { Dropdown } from '@stainless-api/docs/components';
 
@@ -49,11 +49,11 @@ import {
   PROPERTY_SETTINGS,
   ENABLE_CONTEXT_MENU,
 } from 'virtual:stl-starlight-virtual-module';
-import style from '@stainless-api/docs-ui/src/style';
+import style from '@stainless-api/docs-ui/style';
 import { createHighlighter, type BundledLanguage, type BundledTheme, type HighlighterGeneric } from 'shiki';
 import { SnippetCode, SnippetContainer, SnippetRequestContainer } from '../components/SnippetCode';
 import type { StlStarlightMiddleware } from '../middlewareBuilder/stainlessMiddleware';
-import { ComponentProvider } from '@stainless-api/docs-ui/src/contexts/component';
+import { ComponentProvider } from '@stainless-api/docs-ui/contexts/component';
 import { AIDropdown } from '../../stl-docs/components/AIDropdown';
 import { ChevronsUpDownIcon } from 'lucide-react';
 

package/plugin/replaceSidebarPlaceholderMiddleware.ts

@@ -5,7 +5,7 @@ import { BASE_PATH } from 'virtual:stl-starlight-virtual-module';
 import { getAPIReferencePlaceholderItems } from './referencePlaceholderUtils';
 import { getMethodFromSDKJSON, recursiveReplacePlaceholderItems } from './generateAPIReferenceLink';
 import { forceGenerateRoute } from './cms/sidebar-builder';
-import { parseRoute } from '@stainless-api/docs-ui/src/routing';
+import { parseRoute } from '@stainless-api/docs-ui/routing';
 
 // this fn is loaded in the plugin via addRouteMiddleware
 

package/plugin/routes/Docs.astro

@@ -8,7 +8,7 @@ import {
   RenderSpec,
   astroMarkdownRender,
 } from '../react/Routing';
-import { getResourceFromSpec } from '@stainless-api/docs-ui/src/utils';
+import { getResourceFromSpec } from '@stainless-api/docs-ui/utils';
 import { BASE_PATH, CONTENT_PANEL_LAYOUT, MIDDLEWARE } from 'virtual:stl-starlight-virtual-module';
 
 const spec = await cmsClient.getSpec();

package/plugin/routes/Overview.astro

@@ -2,7 +2,7 @@
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
 import { EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
 import { cmsClient } from '../cms/client';
-import type { DocsLanguage } from '@stainless-api/docs-ui/src/routing';
+import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
 import { RenderLibraries, RenderSpecOverview, type SpecMetadata } from '../react/Routing';
 
 const spec = await cmsClient.getSpec();

package/plugin/routes/markdown.ts

@@ -1,12 +1,12 @@
 import type { APIRoute, GetStaticPaths } from 'astro';
 import { cmsClient } from '../cms/client';
 import { generateDocsRoutes, getReadmeContent } from '../react/Routing';
-import { getResourceFromSpec } from '@stainless-api/docs-ui/src/utils';
+import { getResourceFromSpec } from '@stainless-api/docs-ui/utils';
 
-import { renderMarkdown } from '@stainless-api/docs-ui/src/markdown';
+import { renderMarkdown } from '@stainless-api/docs-ui/markdown';
 
-import { parseStainlessPath, type DocsLanguage } from '@stainless-api/docs-ui/src/routing';
-import type { EnvironmentType } from '@stainless-api/docs-ui/src/markdown/utils';
+import { parseStainlessPath, 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';
 
 type RouteProps = {

package/scripts/vendor_deps.ts

@@ -3,7 +3,7 @@ import fs from 'fs';
 import path from 'path';
 import { z } from 'zod';
 
-import { Languages } from '@stainless-api/docs-ui/src/routing';
+import { Languages } from '@stainless-api/docs-ui/routing';
 
 const DEPS_DIR = './plugin/vendor';
 

package/stl-docs/components/ContentBreadcrumbs.tsx

@@ -1,6 +1,6 @@
 import { ChevronRight } from 'lucide-react';
-import { Join } from '@stainless-api/docs-ui/src/components';
-import style from '@stainless-api/docs-ui/src/style';
+import { Join } from '@stainless-api/docs-ui/components';
+import style from '@stainless-api/docs-ui/style';
 import type { StarlightRouteData } from '@astrojs/starlight/route-data';
 
 type Breadcrumb = { title: string; href: string };

package/stl-docs/components/PageTitle.astro

@@ -1,5 +1,9 @@
 ---
-import { ENABLE_PROSE_MARKDOWN_RENDERING, ENABLE_CONTEXT_MENU } from 'virtual:stl-docs-virtual-module';
+import {
+  ENABLE_PROSE_MARKDOWN_RENDERING,
+  ENABLE_CONTEXT_MENU,
+  RENDER_PAGE_DESCRIPTIONS,
+} 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';
@@ -49,6 +53,9 @@ function shouldShowAIDropdown() {
 }
 
 const showAIDropdown = shouldShowAIDropdown();
+
+const description = Astro.locals.starlightRoute.entry.data.description;
+const shouldRenderDescription = RENDER_PAGE_DESCRIPTIONS;
 ---
 
 {
@@ -59,6 +66,17 @@ const showAIDropdown = shouldShowAIDropdown();
         {showAIDropdown && <AIDropdown />}
       </div>
       <Default />
+      {!!description && shouldRenderDescription && <p class="description">{description}</p>}
     </>
   )
 }
+
+<style>
+  p.description {
+    font-size: var(--stl-ui-type-scale-text-xl);
+    font-weight: 400;
+    line-height: 1.4;
+    letter-spacing: -0.02em;
+    margin-top: 0.4em;
+  }
+</style>

package/stl-docs/index.ts

@@ -18,6 +18,7 @@ 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';
@@ -159,7 +160,8 @@ function stainlessDocsIntegration(
                       ENABLE_PROSE_MARKDOWN_RENDERING: config.enableProseMarkdownRendering,
                       // TODO: do not duplicate this between both virtual modules
                       ENABLE_CONTEXT_MENU: config.contextMenu,
-                    });
+                      RENDER_PAGE_DESCRIPTIONS: config.renderPageDescriptions,
+                    } satisfies typeof StlDocsVirtualModule);
                   }
                 },
               },

package/stl-docs/loadStlDocsConfig.ts

@@ -46,7 +46,7 @@ type Tabs = {
   /**
    * Whether to hide the tab in the tab bar.
    *
-   * Default: `false`
+   * @default false
    */
   hidden?: boolean;
 }[];
@@ -71,16 +71,23 @@ export type StainlessDocsUserConfig = {
     /**
      * Disable markdown rendering for prose content. Only disable this if it is causing issues.
      *
-     * Default: `false`
+     * @default false
      */
     disableProseMarkdownRendering?: boolean;
   };
   /**
    * Whether to show the context menu with options like "Copy as Markdown" and "Open in ChatGPT".
    *
-   * Default: `true`
+   * @default true
    */
   contextMenu?: boolean;
+
+  /**
+   * Whether to render page descriptions in prose page headers
+   *
+   * @default true
+   */
+  renderPageDescriptions?: boolean;
 } & PassThroughStarlightConfigOptions;
 
 type HeaderLayout = 'default' | 'stacked';
@@ -150,6 +157,7 @@ function normalizeConfig(userConfig: StainlessDocsUserConfig) {
     enableProseMarkdownRendering:
       userConfig.experimental?.disableProseMarkdownRendering === true ? false : true,
     contextMenu: userConfig.contextMenu ?? true,
+    renderPageDescriptions: userConfig.renderPageDescriptions ?? true,
   };
 
   return configWithDefaults;
@@ -158,11 +166,11 @@ function normalizeConfig(userConfig: StainlessDocsUserConfig) {
 export type NormalizedStainlessDocsConfig = ReturnType<typeof normalizeConfig>;
 
 /*
- The goal of the code in this file is to take a user's config and normalize it. 
+ The goal of the code in this file is to take a user's config and normalize it.
  Specifically: we want a single complete config format used throughout the internals of the plugin.
 
  We've tried to avoid any config values being optional/undefined. To accomplish this:
- - Any optional config values should have their defaults set here: eg. basePath defaults to /api 
+ - Any optional config values should have their defaults set here: eg. basePath defaults to /api
  - If a field is only used in certain contexts, we make each context a discriminated union (see SpecRetrieverConfig)
  - We prefer empty arrays over undefined/null
 */

package/theme.css

@@ -14,10 +14,10 @@
 @import '@stainless-api/ui-primitives/styles.css';
 @import './styles/mintlify-compat.css';
 
-@import '@stainless-api/docs-ui/src/styles/resets.css';
-@import '@stainless-api/docs-ui/src/styles/primitives.css';
-@import '@stainless-api/docs-ui/src/styles/main.css';
-@import '@stainless-api/docs-ui/src/styles/snippets.css';
-@import '@stainless-api/docs-ui/src/styles/search.css';
+@import '@stainless-api/docs-ui/styles/resets.css';
+@import '@stainless-api/docs-ui/styles/primitives.css';
+@import '@stainless-api/docs-ui/styles/main.css';
+@import '@stainless-api/docs-ui/styles/snippets.css';
+@import '@stainless-api/docs-ui/styles/search.css';
 
 @import './components/variables.css';

package/virtual-module.d.ts

@@ -1,6 +1,6 @@
 declare module 'virtual:stl-starlight-virtual-module' {
   import type { CreateShikiHighlighterOptions } from '@astrojs/markdown-remark';
-  import type { PropertySettingsType } from '@stainless-api/docs-ui/src/contexts';
+  import type { PropertySettingsType } from '@stainless-api/docs-ui/contexts';
   import type { StlStarlightMiddleware } from '@stainless-api/docs/plugin/MiddlewareTypes';
   import type { StainlessStarlightUserConfig } from './plugin/loadPluginConfig';
 
@@ -44,4 +44,5 @@ declare module 'virtual:stl-docs-virtual-module' {
   export const API_REFERENCE_BASE_PATH: string | null;
   export const ENABLE_PROSE_MARKDOWN_RENDERING: boolean;
   export const ENABLE_CONTEXT_MENU: boolean;
+  export const RENDER_PAGE_DESCRIPTIONS: boolean;
 }