@stainless-api/docs 0.1.0-beta.44 → 0.1.0-beta.46

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @stainless-api/docs
 
+## 0.1.0-beta.46
+
+### Minor Changes
+
+- b61b7c1: New theming system
+
+  A whole new set of design system variables used throughout docs, docs-ui, and ui-primitives
+
+  Improves customizability & uniformness compared to the old set of variables.
+
+### Patch Changes
+
+- Updated dependencies [b61b7c1]
+- Updated dependencies [262f201]
+  - @stainless-api/docs-ui@0.1.0-beta.38
+  - @stainless-api/ui-primitives@0.1.0-beta.27
+
+## 0.1.0-beta.45
+
+### Patch Changes
+
+- 00b33d9: syntax highlighting for markdown renderer
+- fa43cff: json brackets should use muted foreground color
+- c06e5c3: update marked dependency
+- 32d1735: experimental support for collapsible method descriptions
+- Updated dependencies [00b33d9]
+- Updated dependencies [32d1735]
+- Updated dependencies [23254d1]
+  - @stainless-api/ui-primitives@0.1.0-beta.26
+  - @stainless-api/docs-ui@0.1.0-beta.37
+
 ## 0.1.0-beta.44
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.44",
+  "version": "0.1.0-beta.46",
   "publishConfig": {
     "access": "public"
   },
@@ -26,21 +26,21 @@
   "peerDependencies": {
     "@astrojs/starlight": ">=0.36.1",
     "astro": ">=5.15.3",
-    "vite": ">=6.2.1",
     "react": ">=19.0.0",
-    "react-dom": ">=19.0.0"
+    "react-dom": ">=19.0.0",
+    "vite": ">=6.2.1"
   },
   "dependencies": {
     "@astrojs/markdown-remark": "^6.3.9",
     "@astrojs/react": "^4.4.2",
-    "@stainless-api/sdk": "0.1.0-alpha.12",
+    "@stainless-api/sdk": "0.1.0-alpha.16",
+    "astro-expressive-code": "^0.41.3",
     "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.554.0",
-    "marked": "^16.4.2",
+    "marked": "^17.0.1",
     "node-html-parser": "^7.0.1",
     "rehype-parse": "^9.0.1",
     "rehype-remark": "^10.0.1",
@@ -51,23 +51,23 @@
     "unified": "^11.0.5",
     "web-worker": "^1.5.0",
     "yaml": "^2.8.1",
-    "@stainless-api/docs-ui": "0.1.0-beta.36",
-    "@stainless-api/ui-primitives": "0.1.0-beta.25"
+    "@stainless-api/ui-primitives": "0.1.0-beta.27",
+    "@stainless-api/docs-ui": "0.1.0-beta.38"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.5",
     "@markdoc/markdoc": "^0.5.4",
     "@types/node": "24.10.1",
-    "@types/react": "^19.2.6",
+    "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
-    "tsx": "^4.20.3",
+    "tsx": "^4.20.6",
     "typescript": "5.9.3",
     "vite": "^6.4.1",
-    "zod": "^4.1.12",
-    "@stainless/eslint-config": "0.1.0-beta.0",
-    "@stainless/sdk-json": "^0.1.0-beta.0"
+    "zod": "^4.1.13",
+    "@stainless/sdk-json": "^0.1.0-beta.0",
+    "@stainless/eslint-config": "0.1.0-beta.0"
   },
   "scripts": {
     "vendor-deps": "pnpm tsx scripts/vendor_deps.ts",

package/plugin/components/MethodDescription.tsx

@@ -0,0 +1,54 @@
+import { MethodDescriptionProps } from '@stainless-api/docs-ui/components';
+import { useComponents } from '@stainless-api/docs-ui/contexts/use-components';
+import style from '@stainless-api/docs-ui/style';
+import { Button } from '@stainless-api/ui-primitives';
+
+function shouldCollapseDescription(description: string) {
+  const MIN_CHARS = 400;
+  const MIN_LINES = 6;
+
+  const lineCount = description.split('\n').length;
+
+  if (description.length >= MIN_CHARS) return true;
+  if (lineCount >= MIN_LINES) return true;
+
+  // Markdown structure often means longer content
+  if (/#\s/.test(description)) return true; // has headings
+  if (/```/.test(description)) return true; // has code blocks
+  if (/^\s*[-*]\s+/m.test(description)) return true; // has lists
+
+  return false;
+}
+
+export function MethodDescription({ description }: MethodDescriptionProps) {
+  const { Markdown } = useComponents();
+
+  if (description) {
+    // Attempt to determine if we should make the description collapsible initially
+    // or not. If we get this right, there will be no FOUC.
+    const collapsible = shouldCollapseDescription(description);
+
+    return (
+      <div className="stl-method-description">
+        <div
+          className={style.MethodDescription}
+          data-stldocs-property-group="method-description"
+          data-collapsed={collapsible ? 'true' : 'false'}
+        >
+          <Markdown content={description} />
+        </div>
+        <div className="stl-method-description-overflow-wrapper">
+          <Button
+            type="button"
+            data-method-description-toggle
+            size="sm"
+            variant="ghost"
+            hidden={!collapsible}
+          >
+            Show more
+          </Button>
+        </div>
+      </div>
+    );
+  }
+}

package/plugin/components/SDKSelect.astro

@@ -53,88 +53,6 @@ const readmeSlug = language === 'http' ? BASE_PATH : `${BASE_PATH}/${language}`;
   )
 }
 
-<style>
-  @layer starlight.core {
-    label {
-      --sl-label-icon-size: 16px;
-      --sl-caret-size: 1.25rem;
-      --sl-inline-padding: 0.5rem;
-      position: relative;
-      display: flex;
-      align-items: center;
-      gap: 0.25rem;
-      color: var(--sl-color-gray-1);
-    }
-
-    label:hover {
-      color: var(--sl-color-gray-2);
-    }
-
-    .icon {
-      position: absolute;
-      top: 50%;
-      transform: translateY(-50%);
-      pointer-events: none;
-      width: 16px;
-    }
-
-    select {
-      padding-block: 0.3rem;
-      padding-inline: calc(var(--sl-label-icon-size) + var(--sl-inline-padding) + 0.5rem)
-        calc(var(--sl-caret-size) + var(--sl-inline-padding) + 0.25rem);
-      margin-inline: calc(var(--sl-inline-padding) * -1);
-      width: calc(var(--sl-select-width) + var(--sl-inline-padding) * 2);
-      text-overflow: ellipsis;
-      color: inherit;
-      cursor: pointer;
-      appearance: none;
-      font-weight: 600;
-      text-transform: capitalize;
-    }
-
-    select:active {
-      font-weight: inherit;
-      /* font-family: sans-serif;
-      font-weight: 400; */
-    }
-
-    option {
-      background-color: var(--sl-color-bg-nav);
-      color: var(--sl-color-gray-1);
-    }
-
-    @media (min-width: 50rem) {
-      select {
-        font-size: var(--sl-text-sm);
-      }
-    }
-  }
-
-  @layer starlight.components {
-    .label-icon {
-      font-size: var(--sl-label-icon-size);
-      inset-inline-start: 0;
-    }
-
-    .caret {
-      font-size: var(--sl-caret-size);
-      inset-inline-end: 0;
-    }
-  }
-
-  .custom-select-wrapper {
-    --sl-inline-padding: 0.5rem;
-    position: relative;
-    display: inline-block;
-    /* These match the padding on the sidebar menu */
-    padding-left: var(--sl-inline-padding);
-    padding-right: var(--sl-inline-padding);
-
-    .icon.http path {
-      fill: var(--sl-color-text);
-    }
-  }
-</style>
 <script>
   import { navigate } from 'astro:transitions/client';
   import { updateSelectedLanguage } from '../languages';

package/plugin/components/search/SearchIsland.tsx

@@ -38,7 +38,10 @@ async function createMarkdownRenderer(): Promise<MarkdownContext> {
         transform(node, config) {
           const attributes = node.transformAttributes(config);
           const lang = node.attributes.language === 'node' ? 'typescript' : node.attributes.language;
-          const code = highlighter.codeToTokens(node.attributes.content, { lang, theme: 'github-dark' });
+          const code = highlighter.codeToTokens(node.attributes.content, {
+            lang,
+            theme: 'github-dark',
+          });
 
           return new Markdoc.Tag(
             'pre',

package/plugin/globalJs/method-descriptions.ts

@@ -0,0 +1,33 @@
+document.addEventListener('DOMContentLoaded', function () {
+  const COLLAPSED_HEIGHT = 170;
+
+  const container = document.querySelector<HTMLElement>('[data-stldocs-property-group="method-description"]');
+
+  if (!container) return;
+
+  const toggle = document?.querySelector<HTMLButtonElement>('[data-method-description-toggle]');
+  if (!toggle) return;
+
+  // If content isn't tall enough, don't show the button
+  if (container.scrollHeight <= COLLAPSED_HEIGHT + 1) {
+    toggle.hidden = true;
+    container.dataset.collapsed = 'false';
+    return;
+  }
+
+  // Only show button if content is taller than collapsed max height
+  if (container.scrollHeight > COLLAPSED_HEIGHT + 1) {
+    toggle.hidden = false;
+  } else {
+    // Not tall enough to need collapsing — show full content and hide button
+    container.dataset.collapsed = 'false';
+    toggle.hidden = true;
+    return;
+  }
+
+  toggle.addEventListener('click', function () {
+    const isCollapsed = container.dataset.collapsed !== 'false';
+    container.dataset.collapsed = isCollapsed ? 'false' : 'true';
+    toggle.textContent = isCollapsed ? 'Show less' : 'Show more';
+  });
+});

package/plugin/index.ts

@@ -220,6 +220,8 @@ async function stlStarlightAstroIntegration(
                         HIGHLIGHT_THEMES: pluginConfig.highlighting.themes,
                         CONTENT_PANEL_LAYOUT: pluginConfig.contentPanel.layout,
                         EXPERIMENTAL_COLLAPSIBLE_SNIPPETS: pluginConfig.experimentalCollapsibleSnippets,
+                        EXPERIMENTAL_COLLAPSIBLE_METHOD_DESCRIPTIONS:
+                          pluginConfig.experimentalCollapsibleMethodDescriptions,
                         PROPERTY_SETTINGS: pluginConfig.propertySettings,
                         ENABLE_CONTEXT_MENU: pluginConfig.contextMenu,
                       } satisfies Omit<typeof StlStarlightVirtualModule, 'MIDDLEWARE'>),
@@ -308,15 +310,6 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
           }
         }
 
-        const currentExpressiveCode =
-          typeof starlightConfig.expressiveCode === 'object' ? starlightConfig.expressiveCode : {};
-        updateConfig({
-          expressiveCode: {
-            ...currentExpressiveCode,
-            themes: [...(currentExpressiveCode.themes || []), 'github-light', 'github-dark'],
-          },
-        });
-
         updateConfig({
           sidebar: starlightConfig.sidebar,
         });

package/plugin/loadPluginConfig.ts

@@ -116,6 +116,14 @@ export type StainlessStarlightUserConfig = {
    */
   experimentalCollapsibleSnippets?: boolean;
 
+  /**
+   * Enable experimental collapsible method descriptions. Method descriptions will be
+   * collapsed if their content exceeds a certain length.
+   *
+   * @default false
+   */
+  experimentalCollapsibleMethodDescriptions?: boolean;
+
   /**
    * Whether to show the context menu with options like "Copy as Markdown" and "Open in ChatGPT".
    *
@@ -247,6 +255,7 @@ function normalizeConfig(partial: SomeStainlessStarlightUserConfig, command: Ast
       layout: partial.contentPanel?.layout ?? 'double-pane',
     },
     experimentalCollapsibleSnippets: partial.experimentalCollapsibleSnippets ?? false,
+    experimentalCollapsibleMethodDescriptions: partial.experimentalCollapsibleMethodDescriptions ?? false,
     propertySettings: {
       types: partial.propertySettings?.types ?? 'rich',
       collapseDescription: partial.propertySettings?.collapseDescription ?? true,

package/plugin/react/Routing.tsx

@@ -1,20 +1,23 @@
 import * as React from 'react';
-import { marked } from 'marked';
-import hljs from 'highlight.js';
-import { createMarkdownProcessor, type MarkdownProcessor } from '@astrojs/markdown-remark';
+import { marked, Tokens } from 'marked';
+
+import {
+  createMarkdownProcessor,
+  CreateShikiHighlighterOptions,
+  type MarkdownProcessor,
+} from '@astrojs/markdown-remark';
 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/routing';
+import { LanguageNames, SupportedLanguageSyntaxes, type DocsLanguage } from '@stainless-api/docs-ui/routing';
 
 import {
   generateRouteList,
   generateRoute,
   parseStainlessPath,
   walkTree,
-  SupportedLanguageSyntaxes,
   getLanguageSnippet,
 } from '@stainless-api/docs-ui/routing';
 
@@ -48,14 +51,16 @@ import {
   BREADCRUMB_CONFIG,
   PROPERTY_SETTINGS,
   ENABLE_CONTEXT_MENU,
+  EXPERIMENTAL_COLLAPSIBLE_METHOD_DESCRIPTIONS,
 } from 'virtual:stl-starlight-virtual-module';
 import style from '@stainless-api/docs-ui/style';
-import { createHighlighter, type BundledLanguage, type BundledTheme, type HighlighterGeneric } from 'shiki';
+import { BundledTheme, createHighlighter, HighlighterGeneric, type BundledLanguage } from 'shiki';
 import { SnippetCode, SnippetContainer, SnippetRequestContainer } from '../components/SnippetCode';
 import type { StlStarlightMiddleware } from '../middlewareBuilder/stainlessMiddleware';
 import { ComponentProvider } from '@stainless-api/docs-ui/contexts/component';
 import { AIDropdown } from '../../stl-docs/components/AIDropdown';
 import { ChevronsUpDownIcon } from 'lucide-react';
+import { MethodDescription } from '../components/MethodDescription';
 
 export function generateDocsRoutes(spec: SDKJSON.Spec) {
   const paths = generateRouteList({
@@ -151,19 +156,58 @@ export function buildPageNavigation(resource: SDKJSON.Resource, depth: number =
   return [...output, ...subs];
 }
 
-function renderMarkdown(content: string) {
-  return marked.parse(content, { gfm: true }) as string;
+async function renderMarkdown(content: string) {
+  const highlighter = await astroHighlight();
+
+  const renderer = {
+    code({ text, lang }: Tokens.Code) {
+      return shikiHighlight({
+        highlighter,
+        content: text,
+        language: lang,
+      });
+    },
+  };
+
+  marked.use({ renderer });
+  return marked.parse(content, {
+    gfm: true,
+  }) as string;
 }
 
-async function highlight(content: string, language?: string) {
-  if (language === 'json') return hljs.highlight(content, { language }).value;
-  const highlighter = await astroHighlight();
+function shikiHighlight({
+  highlighter,
+  content,
+  language,
+  themes,
+}: {
+  highlighter: HighlighterGeneric<BundledLanguage, BundledTheme>;
+  content: string;
+  language?: string;
+  themes?: CreateShikiHighlighterOptions['themes'] | Record<string, 'stainless-docs-json'>;
+}) {
+  let _themes = themes;
+  if (!themes && language === 'json') {
+    _themes = {
+      light: 'stainless-docs-json',
+      dark: 'stainless-docs-json',
+    };
+  }
+
+  if (!_themes) {
+    _themes = HIGHLIGHT_THEMES;
+  }
   return highlighter.codeToHtml(content, {
     lang: language ?? 'javascript',
-    themes: HIGHLIGHT_THEMES || {},
+    themes: _themes || {},
   });
 }
 
+async function highlight(content: string, language?: string) {
+  const highlighter = await astroHighlight();
+  return shikiHighlight({ highlighter, content, language });
+}
+
 export function SDKSelectReactComponent({
   selected,
   languages,
@@ -327,6 +371,7 @@ export function RenderSpec({
           SnippetCode,
           SnippetContainer,
           SnippetRequestContainer,
+          ...(EXPERIMENTAL_COLLAPSIBLE_METHOD_DESCRIPTIONS ? { MethodDescription } : {}),
         }}
       >
         <NavigationProvider basePath={BASE_PATH} selectedPath={path}>
@@ -392,6 +437,66 @@ export async function getReadmeContent(spec: SDKJSON.Spec, language: DocsLanguag
   return spec.readme[language];
 }
 
+let astroShikiHighlighter:
+  | HighlighterGeneric<BundledLanguage, BundledTheme>
+  | Promise<HighlighterGeneric<BundledLanguage, BundledTheme>>
+  | null = null;
+
+async function astroHighlight() {
+  if (astroShikiHighlighter) {
+    return astroShikiHighlighter;
+  }
+
+  astroShikiHighlighter = createHighlighter({
+    themes: [
+      'github-light',
+      'github-dark',
+      {
+        name: 'stainless-docs-json',
+        colors: {
+          'editor.background': 'var(--stl-color-background)',
+          'editor.foreground': 'var(--stl-color-foreground)',
+        },
+
+        tokenColors: [
+          {
+            scope: ['comment', 'punctuation.definition.comment'],
+            settings: { foreground: 'var(--stl-color-foreground-muted)' },
+          },
+          // numbers, booleans, null
+          {
+            scope: ['constant.numeric', 'constant.language'],
+            settings: { foreground: 'var(--stl-color-foreground-orange)' },
+          },
+          // strings
+          {
+            scope: ['string', 'string.quoted', 'string.template'],
+            settings: { foreground: 'var(--stl-color-foreground-green)' },
+          },
+          // Keys, brackets
+          {
+            scope: ['support.type', 'meta'],
+            settings: { foreground: 'var(--stl-color-foreground)' },
+          },
+          // brackets
+          {
+            scope: ['meta'],
+            settings: { foreground: 'var(--stl-color-foreground-muted)' },
+          },
+          // built-in types
+          {
+            scope: ['support.type.builtin'],
+            settings: { foreground: 'var(--stl-color-foreground-purple)' },
+          },
+        ],
+      },
+    ],
+    langs: SupportedLanguageSyntaxes,
+  });
+
+  return astroShikiHighlighter;
+}
+
 // Astro's markdown processor is a singleton
 // Need to cache it instead of instanting per request
 let astroMarkdownProcessor: MarkdownProcessor;
@@ -409,18 +514,6 @@ async function astroMarkdown() {
   return astroMarkdownProcessor;
 }
 
-let astroShikiHighlighter: HighlighterGeneric<BundledLanguage, BundledTheme>;
-async function astroHighlight() {
-  if (!astroShikiHighlighter) {
-    astroShikiHighlighter = await createHighlighter({
-      themes: ['github-light', 'github-dark'],
-      langs: SupportedLanguageSyntaxes,
-    });
-  }
-
-  return astroShikiHighlighter;
-}
-
 export async function astroMarkdownRender(content: string) {
   const md = await astroMarkdown();
   const output = await md.render(content);

package/plugin/routes/Docs.astro

@@ -143,3 +143,4 @@ if (readme) {
 <script src="../globalJs/copy.ts"></script>
 <script src="../globalJs/tooltip.ts"></script>
 <script src="../globalJs/code-snippets.ts"></script>
+<script src="../globalJs/method-descriptions.ts"></script>

package/stl-docs/components/Header.astro

@@ -23,12 +23,9 @@ const shouldRenderSearch = !!(
 
 <style is:global>
   @layer starlight.core {
-    header {
-      border-color: var(--sl-color-hairline);
-
-      &.header {
-        border-bottom-color: var(--sl-color-hairline);
-      }
+    header,
+    header.header {
+      border-color: var(--stl-color-border-faint);
     }
 
     .header {

package/stl-docs/components/PageTitle.astro

@@ -73,7 +73,7 @@ const shouldRenderDescription = RENDER_PAGE_DESCRIPTIONS;
 
 <style>
   p.description {
-    font-size: var(--stl-ui-type-scale-text-xl);
+    font-size: var(--stl-typography-scale-xl);
     font-weight: 400;
     line-height: 1.4;
     letter-spacing: -0.02em;