@stainless-api/docs 0.1.0-beta.13 → 0.1.0-beta.131

package/stl-docs/proseSearchIndexing.ts

@@ -0,0 +1,218 @@
+import type { AstroIntegration } from 'astro';
+import { readFile } from 'fs/promises';
+import { getProsePages } from '../shared/getProsePages';
+import { getSharedLogger } from '../shared/getSharedLogger';
+import { bold } from '../shared/terminalUtils';
+import * as cheerio from 'cheerio';
+import { buildProseIndex } from '@stainless-api/docs-search/providers/algolia';
+
+class SectionContext {
+  headers: { level: number; text: string }[] = [];
+  headerId: string | undefined;
+  headerTag: string | undefined;
+  headerText: string | undefined;
+  hasContent = false;
+
+  get(): string | undefined {
+    if (this.headers.length === 0) return;
+    return this.headers.map((h) => h.text).join(' > ');
+  }
+
+  header({ id, tag, text }: { id: string; tag: string; text: string }) {
+    const level = getHeaderLevel(tag);
+    if (level > 0) {
+      while (this.headers.length > 0 && this.headers[this.headers.length - 1]!.level >= level) {
+        this.headers.pop();
+      }
+      this.headers.push({ level, text });
+    }
+    this.headerId = id;
+    this.headerTag = tag;
+    this.headerText = text;
+    this.hasContent = false;
+  }
+}
+
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/`/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+function getHeaderLevel(tag: string): number {
+  const match = tag.match(/^h(\d)$/);
+  return match ? parseInt(match[1]!, 10) : 0;
+}
+
+// Chunking configuration
+// We target 64-256 tokens per chunk, using ~1.3 tokens/word for English text
+const TOKENS_PER_WORD = 1.3;
+const MIN_TOKENS = 64;
+const MAX_TOKENS = 256;
+const MIN_WORDS = Math.floor(MIN_TOKENS / TOKENS_PER_WORD); // ~49 words
+const MAX_WORDS = Math.floor(MAX_TOKENS / TOKENS_PER_WORD); // ~197 words
+const SENTENCE_BREAK_WORDS = Math.floor((MAX_TOKENS * 0.875) / TOKENS_PER_WORD); // ~172 words
+
+/**
+ * Chunks text content into segments of 64-256 tokens using word-based boundaries.
+ * Prefers breaking at sentence endings for natural chunk boundaries.
+ */
+function chunkTextByWords(text: string): string[] {
+  const words = text.split(/\s+/).filter((w) => w.length > 0);
+
+  if (words.length <= MAX_WORDS) {
+    return words.length > 0 ? [words.join(' ')] : [];
+  }
+
+  const chunks: string[] = [];
+  let currentChunk: string[] = [];
+
+  for (const word of words) {
+    currentChunk.push(word);
+
+    // Force break at max words
+    if (currentChunk.length >= MAX_WORDS) {
+      chunks.push(currentChunk.join(' '));
+      currentChunk = [];
+      continue;
+    }
+
+    // Prefer breaking at sentence boundaries after threshold
+    if (currentChunk.length >= SENTENCE_BREAK_WORDS && /[.!?]["']?$/.test(word)) {
+      chunks.push(currentChunk.join(' '));
+      currentChunk = [];
+    }
+  }
+
+  if (currentChunk.length > 0) {
+    if (currentChunk.length < MIN_WORDS && chunks.length > 0) {
+      const lastChunk = chunks[chunks.length - 1]!;
+      const mergedWords = lastChunk.split(/\s+/).length + currentChunk.length;
+      if (mergedWords <= MAX_WORDS) {
+        chunks[chunks.length - 1] = lastChunk + ' ' + currentChunk.join(' ');
+      } else {
+        chunks.push(currentChunk.join(' '));
+      }
+    } else {
+      chunks.push(currentChunk.join(' '));
+    }
+  }
+
+  return chunks;
+}
+
+type IndexEntry = {
+  chunk: { id: string; index: number; total: number };
+  id: string;
+  tag: string;
+  content: string;
+  language?: string;
+  sectionContext?: string;
+};
+
+const DEFAULT_ROOT = 'main';
+const DEFAULT_PATTERN = 'h1, h2, h3, h4, h5, h6, p, li, pre code';
+
+/**
+ * Indexes HTML content for search, with section context and code language extraction.
+ *
+ * Features:
+ * - Tracks header hierarchy to prepend section context (e.g., "Guide > Setup: ...")
+ * - Extracts language metadata from code blocks (class="language-js")
+ * - Uses word-based chunking with sentence boundary detection
+ */
+function* indexHTML(content: string, root = DEFAULT_ROOT, pattern = DEFAULT_PATTERN): Generator<IndexEntry> {
+  const $ = cheerio.load(content);
+  const matches = $(root).find(pattern);
+
+  const ctx = new SectionContext();
+
+  for (const match of matches) {
+    const tagName = match.tagName.toLowerCase();
+    const rawText = $(match).text().trim();
+
+    if (getHeaderLevel(tagName) > 0) {
+      ctx.header({ id: $(match).attr('id') ?? slugify(rawText), tag: tagName, text: rawText });
+      continue;
+    }
+
+    // Check if this is a code block and extract language
+    const isCode = tagName === 'code' && $(match).parent().is('pre');
+    let language: string | undefined;
+    if (isCode) {
+      const classes = $(match).attr('class') || '';
+      const langMatch = classes.match(/(?:language-|lang-)([a-zA-Z0-9+-]+)/);
+      language = langMatch ? langMatch[1] : undefined;
+    }
+
+    // Build content with section context
+    const sectionContext = ctx.get();
+    const chunks = chunkTextByWords(rawText);
+    const chunkId = crypto.randomUUID();
+
+    for (const [chunkN, chunkText] of chunks.entries()) {
+      yield {
+        id: ctx.headerId ?? $(match).attr('id') ?? chunkId,
+        tag: isCode ? 'code' : tagName,
+        content: chunkText,
+        ...(sectionContext ? { sectionContext } : {}),
+        ...(language && { language }),
+        chunk: {
+          id: chunkId,
+          index: chunkN,
+          total: chunks.length,
+        },
+      };
+      ctx.hasContent = true;
+    }
+  }
+}
+
+export function stainlessDocsAlgoliaProseIndexing({
+  apiReferenceBasePath,
+}: {
+  apiReferenceBasePath: string | null;
+}): AstroIntegration {
+  return {
+    name: 'stl-docs-prose-indexing',
+    hooks: {
+      'astro:build:done': async ({ logger: localLogger, dir }) => {
+        const logger = getSharedLogger({ fallback: localLogger });
+        const outputBasePath = dir.pathname;
+
+        const {
+          PUBLIC_ALGOLIA_APP_ID: appId,
+          PUBLIC_ALGOLIA_INDEX: indexName,
+          PRIVATE_ALGOLIA_WRITE_KEY: algoliaWriteKey,
+        } = process.env;
+
+        if (!appId || !indexName || !algoliaWriteKey) {
+          logger.info('Skipping algolia indexing due to missing environment variables');
+          return;
+        }
+
+        const pagesToRender = await getProsePages({ apiReferenceBasePath, outputBasePath });
+        logger.info(bold(`Indexing ${pagesToRender.length} prose pages for algolia search`));
+
+        const objects = [];
+        for (const absHtmlPath of pagesToRender) {
+          const content = await readFile(absHtmlPath, 'utf-8');
+          const idx = indexHTML(content);
+          for (const entry of idx)
+            objects.push({
+              ...entry,
+              source: absHtmlPath.slice(outputBasePath.length),
+            });
+        }
+
+        try {
+          await buildProseIndex(appId, `${indexName}-prose`, algoliaWriteKey, objects);
+        } catch (err) {
+          logger.error(`Failed to index prose content: ${err}`);
+        }
+      },
+    },
+  };
+}

package/stl-docs/tabsMiddleware.ts

@@ -3,6 +3,7 @@ import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
 
 import { SPLIT_TABS_ENABLED, TABS } from 'virtual:stl-docs-virtual-module';
 import clsx from 'clsx';
+import path from 'path';
 
 // this fn is loaded in the plugin via addRouteMiddleware
 
@@ -58,7 +59,7 @@ function getTabIndexForSlug(
   match: 'exact' | 'prefix';
 } | null {
   // ↓ exact match eg. slug = "/blog" and there is a link containing "/blog"
-  let tab = linksByTab.get(slug);
+  const tab = linksByTab.get(slug)!;
   if (typeof tab === 'string') {
     return {
       match: 'exact',
@@ -88,18 +89,24 @@ function getNonSplitLinksByTab() {
   const linksByTab = new Map<string, string>();
 
   for (let i = 0; i < TABS.length; i++) {
-    const tab = TABS[i];
+    const tab = TABS[i]!;
     linksByTab.set(tab.link, String(i));
   }
 
   return linksByTab;
 }
 
-export const onRequest = defineRouteMiddleware(async (context) => {
+export interface StarlightRouteWithStlDocs extends StarlightRouteData {
+  _stlDocs?: {
+    activeTabIndex: number;
+  };
+}
+
+export const onRequest = defineRouteMiddleware((context) => {
   // if using content collection schema, use: context.locals.starlightRoute.entry.data.stainlessStarlight
   // this worked without collections but relied on hijacking starlightRoute: context.props.frontmatter.stainlessStarlight
 
-  const slug = `/${context.locals.starlightRoute.id}`; // same as .slug but not deprecated
+  const slug = path.posix.join(import.meta.env.BASE_URL ?? '', context.locals.starlightRoute.id); // same as .slug but not deprecated
 
   /*
     In the index of our starlight plugin, we transform our "tabs" into a plain old Starlight sidebar.
@@ -143,7 +150,8 @@ export const onRequest = defineRouteMiddleware(async (context) => {
   }
 
   // We store the active tab index so we can use it in our nav tabs component
-  context.locals.starlightRoute._stlDocs = {
+  const routeData: StarlightRouteWithStlDocs = context.locals.starlightRoute;
+  routeData._stlDocs = {
     activeTabIndex: activeTabIndex.index,
   };
 
@@ -179,5 +187,6 @@ export const onRequest = defineRouteMiddleware(async (context) => {
 
   matchingGroup?.entries.unshift(...mobileLinks);
 
+  (context.locals._stlStarlightPage ??= {}).fullSidebar = context.locals.starlightRoute.sidebar;
   context.locals.starlightRoute.sidebar = matchingGroup.entries;
 });

package/styles/code.css

@@ -1,6 +1,6 @@
 .expressive-code {
   .frame {
-    --code-background: var(--sl-color-bg-inline-code);
+    --code-background: var(--stl-color-faint-background);
   }
 
   figure.frame {
@@ -10,19 +10,19 @@
   figure,
   pre {
     border-radius: var(--sl-button-border-radius);
-    border-color: var(--sl-color-hairline);
+    border-color: var(--stl-color-border);
   }
 
   .frame.has-title:not(.is-terminal),
   .frame.is-terminal {
     figcaption {
       border-radius: var(--sl-button-border-radius) var(--sl-button-border-radius) 0 0;
-      border-color: var(--sl-color-hairline);
+      border-color: var(--stl-color-border);
     }
 
     pre {
       border-radius: 0 0 var(--sl-button-border-radius) var(--sl-button-border-radius);
-      border-color: var(--sl-color-hairline);
+      border-color: var(--stl-color-border);
     }
   }
 
@@ -32,7 +32,7 @@
     }
 
     .header::before {
-      border-color: var(--sl-color-hairline);
+      border-color: var(--stl-color-border);
     }
 
     .title::after {
@@ -44,7 +44,7 @@
 
 .astro-code {
   border-radius: var(--sl-button-border-radius);
-  border-color: var(--sl-color-hairline);
+  border-color: var(--stl-color-border);
 }
 
 .stl-snippet-request-container {
@@ -52,14 +52,34 @@
 }
 
 .stl-snippet-expand-button {
-  display: none;
-
-  position: relative;
+  position: absolute;
   left: 50%;
-  transform: translateX(-50%);
-  bottom: 12px;
+  transform: translateX(-50%) translateY(-50%);
   cursor: pointer;
   height: auto;
+  z-index: 100;
+
+  &:not(.stl-snippet-collapsible .stl-snippet-expand-button) {
+    display: none;
+  }
+
+  &.stl-ui-button {
+    background-color: var(--stl-color-background);
+    background-image: linear-gradient(
+      to right,
+      var(--stl-color-ui-background),
+      var(--stl-color-ui-background)
+    );
+  }
+
+  &.stl-ui-button:hover {
+    background-color: var(--stl-color-background);
+    background-image: linear-gradient(
+      to right,
+      var(--stl-color-ui-background-hover),
+      var(--stl-color-ui-background-hover)
+    );
+  }
 }
 
 .stl-snippet-code-is-expanded {
@@ -69,13 +89,6 @@
 }
 
 .stl-snippet-collapsible {
-  .stl-snippet-expand-button {
-    display: block;
-    margin-bottom: -23px;
-    /* Prevent clipping of the button with the container below */
-    z-index: 100;
-  }
-
   .stl-snippet-code-is-collapsed {
     .hidden {
       display: none;
@@ -121,35 +134,25 @@
 .stl-snippet-dropdown-button-text {
   font-weight: 500;
   font-style: normal;
-  font-family: var(--stldocs-font);
+  font-family: var(--stl-typography-font);
   line-height: 100%;
-  font-size: var(--sl-text-body-sm);
-  color: var(--sl-color-text);
-  text-transform: capitalize;
-
-  &.http {
-    text-transform: uppercase;
-  }
+  font-size: var(--stl-typography-scale-sm);
+  color: var(--stl-color-foreground);
 }
 
-:root[data-theme='light'] {
+.shiki,
+.astro-code,
+.stldocs-snippet-response-pane {
+  background-color: var(--shiki-background, var(--stl-color-faint-background)) !important;
+  .shiki,
   .astro-code,
-  .astro-code span {
-    background-color: var(--sl-color-bg-inline-code) !important;
-  }
-
   .stldocs-snippet-response-pane {
-    .shiki,
-    .shiki span,
-    .astro-code,
-    .astro-code span {
-      background-color: var(--sl-color-bg-inline-code) !important;
-    }
+    background-color: transparent !important;
   }
 }
 
 :root[data-theme='dark'] {
-  /* 
+  /*
     Need to use important to override inline variables. This is the
     recommended pattern in the shiki docs.
 
@@ -160,23 +163,24 @@
   .astro-code,
   .astro-code span {
     color: var(--shiki-dark) !important;
-    background-color: var(--sl-color-bg) !important;
     font-style: var(--shiki-dark-font-style) !important;
     font-weight: var(--shiki-dark-font-weight) !important;
     text-decoration: var(--shiki-dark-text-decoration) !important;
   }
+}
 
-  .astro-code,
-  .astro-code span {
-    background-color: var(--sl-color-bg-inline-code) !important;
+.stldocs-snippet .stldocs-snippet-footer.try-it-footer {
+  display: none;
+  justify-content: flex-end;
+  gap: 0.5rem;
+
+  /* only show footer if RequestBuilder was rendered successfully */
+  stl-island[component='SnippetStainlessIsland'] & {
+    display: flex;
   }
 
-  .stldocs-snippet-response-pane {
-    .shiki,
-    .shiki span,
-    .astro-code,
-    .astro-code span {
-      background-color: var(--sl-color-bg-inline-code) !important;
-    }
+  .try-it-button,
+  .send-button {
+    width: 7rem;
   }
 }

package/styles/links.css

@@ -1,3 +1,5 @@
+/* TODO: remove for real card component */
+
 .sl-link-card {
   box-shadow: none;
   border-radius: var(--sl-button-border-radius);
@@ -10,40 +12,3 @@
   border: 1px solid var(--sl-color-accent-high);
   background-color: var(--sl-color-accent-low);
 }
-
-.pagination-links {
-  margin-bottom: 2rem;
-
-  > a {
-    border-radius: var(--sl-button-border-radius);
-    border: 1px solid transparent;
-    box-shadow: none;
-    max-width: 90%;
-    text-decoration: none;
-
-    svg {
-      margin-top: 0;
-      transform: translateY(6px);
-    }
-  }
-
-  > a:hover {
-    transition: 0.3s;
-    border: 1px solid var(--sl-color-accent-high);
-    background-color: var(--sl-color-accent-low);
-    box-shadow: none;
-  }
-
-  /* if only one pagination direction */
-  > a:first-child:nth-last-child(1) {
-    max-width: 45%;
-  }
-
-  > a[rel='next'] {
-    margin-left: auto;
-  }
-
-  > a[rel='prev'] {
-    margin-right: auto;
-  }
-}

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(--stl-color-background));
+        pointer-events: none;
+      }
+
+      &[data-collapsed='false'] {
+        max-height: none;
+      }
+
+      &[data-collapsed='false']::after {
+        display: none;
+      }
+    }
+  }
+}

package/styles/overrides.css

@@ -3,8 +3,7 @@ html {
 }
 
 .site-title {
-  color: var(--sl-color-white);
-  max-width: 144px;
+  color: var(--stl-color-foreground);
 
   img {
     height: 32px;
@@ -12,66 +11,49 @@ html {
   }
 }
 
-/* Hide the text in the theme select dropdown */
-starlight-theme-select select {
-  width: 0;
-  overflow: hidden;
-}
-
-.custom-select-wrapper select,
-.stldocs-button-secondary {
-  background-color: var(--sl-color-bg-ui);
-  border: 1px solid var(--sl-color-hairline);
-  border-radius: var(--sl-button-border-radius);
-
-  &:hover {
-    border-color: var(--sl-color-hairline-shade);
-  }
-}
-
-.content-panel {
-  border-top: 0;
-}
-
+/* TODO: apply real button classes here */
 starlight-menu-button button {
   box-shadow: none;
-  background-color: var(--sl-color-bg-ui);
-  border: 1px solid var(--sl-color-hairline);
-  border-radius: var(--sl-button-border-radius);
-  height: var(--sl-button-size);
-  width: var(--sl-button-size);
+  background-color: var(--stl-color-ui-background);
+  border: 1px solid var(--stl-color-border);
+  border-radius: var(--stl-ui-layout-border-radius-sml);
+  height: 32px;
+  width: 32px;
   display: flex;
   align-items: center;
   justify-content: center;
 
   &:hover {
-    border-color: var(--sl-color-hairline-shade);
+    background-color: var(--stl-color-ui-background-hover);
   }
 }
 
 mobile-starlight-toc {
   nav {
-    background-color: var(--sl-color-bg);
+    background-color: var(--stl-color-background);
+  }
+  .toggle {
+    background-color: var(--stl-color-ui-background);
+    border: 1px solid var(--stl-color-border);
+    border-radius: var(--stl-ui-layout-border-radius-sml);
+    &:hover {
+      background-color: var(--stl-color-ui-background-hover);
+      border-color: var(--stl-color-border); /* unchanged */
+    }
+  }
+  .dropdown {
+    background-color: var(--stl-color-background);
+    border-color: var(--stl-color-border-faint);
   }
-
   summary {
     padding: 2rem 1rem;
-    border-bottom-color: var(--sl-color-hairline-light);
+    border-color: var(--stl-color-border-faint);
   }
-}
-
-@media (min-width: 50rem) {
-  starlight-menu-button button {
-    display: none;
+  a {
+    border-color: var(--stl-color-border-faint);
   }
+}
 
-  mobile-starlight-toc {
-    nav {
-      inset-inline-start: calc(var(--sl-content-inline-start, 0));
-    }
-
-    summary {
-      padding: 2rem 2rem;
-    }
-  }
+starlight-menu-button {
+  display: none;
 }