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

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @stainless-api/docs
 
+## 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.45",
   "publishConfig": {
     "access": "public"
   },
@@ -26,21 +26,20 @@
   "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",
     "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,8 +50,8 @@
     "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/docs-ui": "0.1.0-beta.37",
+    "@stainless-api/ui-primitives": "0.1.0-beta.26"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.5",
@@ -62,7 +61,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",

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/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'>),

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-ui-background)',
+          'editor.foreground': 'var(--stl-ui-foreground)',
+        },
+
+        tokenColors: [
+          {
+            scope: ['comment', 'punctuation.definition.comment'],
+            settings: { foreground: 'var(--stl-ui-foreground-muted)' },
+          },
+          // numbers, booleans, null
+          {
+            scope: ['constant.numeric', 'constant.language'],
+            settings: { foreground: 'var(--stl-ui-swatch-orange-base)' },
+          },
+          // strings
+          {
+            scope: ['string', 'string.quoted', 'string.template'],
+            settings: { foreground: 'var(--stl-ui-swatch-green-base)' },
+          },
+          // Keys, brackets
+          {
+            scope: ['support.type', 'meta'],
+            settings: { foreground: 'var(--stl-ui-foreground)' },
+          },
+          // brackets
+          {
+            scope: ['meta'],
+            settings: { foreground: 'var(--stl-ui-foreground-muted)' },
+          },
+          // built-in types
+          {
+            scope: ['support.type.builtin'],
+            settings: { foreground: 'var(--stl-ui-swatch-purple-base)' },
+          },
+        ],
+      },
+    ],
+    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/styles/method-descriptions.css

@@ -0,0 +1,36 @@
+.stldocs-root {
+  .stl-method-description-overflow-wrapper {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    /* Minimum height to minimize layout shift */
+    min-height: 24px;
+  }
+  .stl-method-description {
+    .stldocs-method-description {
+      overflow: hidden;
+      max-height: 170px;
+      transition: max-height 0.3s ease;
+      position: relative;
+
+      &::after {
+        content: '';
+        position: absolute;
+        left: 0;
+        right: 0;
+        bottom: 0;
+        height: 3rem;
+        background: linear-gradient(to bottom, transparent, var(--stldocs-color-bg));
+        pointer-events: none;
+      }
+
+      &[data-collapsed='false'] {
+        max-height: none;
+      }
+
+      &[data-collapsed='false']::after {
+        display: none;
+      }
+    }
+  }
+}

package/theme.css

@@ -11,13 +11,13 @@
 @import './styles/overrides.css';
 @import './styles/code.css';
 @import './styles/sdk_select.css';
+@import './styles/method-descriptions.css';
 @import '@stainless-api/ui-primitives/styles.css';
 @import './styles/mintlify-compat.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

@@ -14,6 +14,7 @@ declare module 'virtual:stl-starlight-virtual-module' {
   export const HIGHLIGHT_THEMES: CreateShikiHighlighterOptions['themes'];
   export const CONTENT_PANEL_LAYOUT: 'double-pane' | 'single-pane';
   export const EXPERIMENTAL_COLLAPSIBLE_SNIPPETS: boolean | undefined;
+  export const EXPERIMENTAL_COLLAPSIBLE_METHOD_DESCRIPTIONS: boolean | undefined;
   export const PROPERTY_SETTINGS: PropertySettingsType;
   export const MIDDLEWARE: StlStarlightMiddleware;
   export const ENABLE_CONTEXT_MENU: boolean;