@stainless-api/docs 0.1.0-beta.67 → 0.1.0-beta.69

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @stainless-api/docs
 
+## 0.1.0-beta.69
+
+### Patch Changes
+
+- 67aa6b5: improves UI for algolia search on desktop and mobile
+- bf9bdd4: Remove old/broken mintlify-compat Steps implementation in favor of the new component
+- 68f4528: Adds support for opengraph images
+- Updated dependencies [67aa6b5]
+  - @stainless-api/docs-search@0.1.0-beta.6
+  - @stainless-api/docs-ui@0.1.0-beta.54
+
+## 0.1.0-beta.68
+
+### Patch Changes
+
+- add prose docs vector indexing
+
 ## 0.1.0-beta.67
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.67",
+  "version": "0.1.0-beta.69",
   "publishConfig": {
     "access": "public"
   },
@@ -17,7 +17,11 @@
     "./font-imports": "./styles/fonts.css",
     "./components": "./stl-docs/components/index.ts",
     "./components/scripts": "./stl-docs/components/scripts.ts",
-    "./components/Head": "./stl-docs/components/Head.astro"
+    "./docs-config": "./stl-docs/loadStlDocsConfig.ts",
+    "./cms-client": "./plugin/cms/client.ts",
+    "./generate-docs-routes": "./plugin/helpers/generateDocsRoutes.ts",
+    "./components/Head": "./stl-docs/components/Head.astro",
+    "./components/ContentBreadcrumbs": "./stl-docs/components/ContentBreadcrumbs.tsx"
   },
   "keywords": [],
   "author": "",
@@ -36,6 +40,7 @@
     "@astrojs/markdown-remark": "^6.3.10",
     "@astrojs/react": "^4.4.2",
     "@stainless-api/sdk": "0.1.0-alpha.19",
+    "astro-expressive-code": "^0.41.3",
     "cheerio": "^1.1.2",
     "clsx": "^2.1.1",
     "dotenv": "17.2.3",
@@ -53,8 +58,8 @@
     "vite-plugin-prebundle-workers": "^0.2.0",
     "web-worker": "^1.5.0",
     "yaml": "^2.8.2",
-    "@stainless-api/docs-search": "0.1.0-beta.5",
-    "@stainless-api/docs-ui": "0.1.0-beta.53",
+    "@stainless-api/docs-search": "0.1.0-beta.6",
+    "@stainless-api/docs-ui": "0.1.0-beta.54",
     "@stainless-api/ui-primitives": "0.1.0-beta.40"
   },
   "devDependencies": {

package/plugin/components/search/SearchAlgolia.astro

@@ -1,7 +1,7 @@
 ---
-import { Icon } from '@astrojs/starlight/components';
 import { DocsSearch } from './SearchIsland';
 import { Button } from '@stainless-api/ui-primitives';
+import { SearchIcon, XIcon } from 'lucide-react';
 ---
 
 <site-search>
@@ -13,7 +13,8 @@ import { Button } from '@stainless-api/ui-primitives';
     variant="outline"
     className="stl-algolia-search"
   >
-    <Icon name="magnifier" />
+    <SearchIcon className="icon-search" size={14} />
+    <XIcon className="icon-close" size={14} />
     <span class="sl-hidden md:sl-block" aria-hidden="true">{Astro.locals.t('search.label')}</span>
     <kbd class="sl-hidden md:sl-flex" style="display: none;">
       <kbd>{Astro.locals.t('search.ctrlKey')}</kbd><kbd>K</kbd>
@@ -65,4 +66,32 @@ import { Button } from '@stainless-api/ui-primitives';
     width: unset;
     flex-grow: 1;
   }
+  .stl-algolia-search {
+    padding: 0;
+  }
+  @media (min-width: 50rem) {
+    .stl-algolia-search {
+      padding: 8px 10px;
+    }
+  }
+
+  .stl-algolia-search {
+    .icon-search {
+      display: inline;
+    }
+
+    .icon-close {
+      display: none;
+    }
+  }
+
+  site-search:has(#stldocs-search[data-stldocs-modal-open='true']) .stl-algolia-search {
+    .icon-search {
+      display: none;
+    }
+
+    .icon-close {
+      display: inline;
+    }
+  }
 </style>

package/plugin/helpers/generateDocsRoutes.ts

@@ -0,0 +1,27 @@
+import type * as SDKJSON from '@stainless/sdk-json';
+import { DocsLanguage, generateRouteList } from '@stainless-api/docs-ui/routing';
+import { EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
+
+export function generateDocsRoutes(spec: SDKJSON.Spec, excludeLanguages: DocsLanguage[] = EXCLUDE_LANGUAGES) {
+  const paths = generateRouteList({
+    spec,
+    excludeLanguages,
+  });
+  const readmes = Object.entries(spec.readme)
+    .filter(([language]) => language !== 'http')
+    .filter(([language]) => !excludeLanguages.includes(language as DocsLanguage))
+    .map(([language]) => ({
+      slug: language,
+      stainlessPath: null,
+      language: language as DocsLanguage,
+      title: 'Readme',
+      kind: 'readme',
+    }));
+
+  return [...paths, ...readmes].map(({ slug, stainlessPath, language, title, kind }) => {
+    return {
+      params: { slug },
+      props: { stainlessPath, language, title, kind },
+    };
+  });
+}

package/plugin/react/Routing.tsx

@@ -14,7 +14,6 @@ import type * as SDKJSON from '@stainless/sdk-json';
 import { LanguageNames, SupportedLanguageSyntaxes, type DocsLanguage } from '@stainless-api/docs-ui/routing';
 
 import {
-  generateRouteList,
   generateRoute,
   parseStainlessPath,
   walkTree,
@@ -67,30 +66,6 @@ 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({
-    spec,
-    excludeLanguages: EXCLUDE_LANGUAGES as DocsLanguage[],
-  });
-  const readmes = Object.entries(spec.readme)
-    .filter(([language]) => language !== 'http')
-    .filter(([language]) => !EXCLUDE_LANGUAGES.includes(language as DocsLanguage))
-    .map(([language]) => ({
-      slug: language,
-      stainlessPath: null,
-      language: language as DocsLanguage,
-      title: 'Readme',
-      kind: 'readme',
-    }));
-
-  return [...paths, ...readmes].map(({ slug, stainlessPath, language, title, kind }) => {
-    return {
-      params: { slug },
-      props: { stainlessPath, language, title, kind },
-    };
-  });
-}
-
 function isResourceNonEmpty(resource: SDKJSON.Resource) {
   return (
     Object.keys(resource.methods ?? {}).length > 0 ||

package/plugin/routes/Docs.astro

@@ -1,15 +1,10 @@
 ---
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
 import { cmsClient } from '../cms/client';
-import {
-  getReadmeContent,
-  generateDocsRoutes,
-  buildPageNavigation,
-  RenderSpec,
-  astroMarkdownRender,
-} from '../react/Routing';
+import { getReadmeContent, buildPageNavigation, RenderSpec, astroMarkdownRender } from '../react/Routing';
 import { getResourceFromSpec } from '@stainless-api/docs-ui/utils';
 import { BASE_PATH, CONTENT_PANEL_LAYOUT, MIDDLEWARE } from 'virtual:stl-starlight-virtual-module';
+import { generateDocsRoutes } from '../helpers/generateDocsRoutes';
 
 const spec = await cmsClient.getSpec();
 const routes = generateDocsRoutes(spec);

package/plugin/routes/DocsStatic.astro

@@ -2,7 +2,7 @@
 import type { GetStaticPaths } from 'astro';
 import Docs from './Docs.astro';
 import { cmsClient } from '../cms/client';
-import { generateDocsRoutes } from '../react/Routing';
+import { generateDocsRoutes } from '../helpers/generateDocsRoutes';
 
 export const getStaticPaths = (async () => {
   const spec = await cmsClient.getSpec();

package/plugin/routes/markdown.ts

@@ -1,6 +1,6 @@
 import type { APIRoute, GetStaticPaths } from 'astro';
 import { cmsClient } from '../cms/client';
-import { generateDocsRoutes, getReadmeContent } from '../react/Routing';
+import { getReadmeContent } from '../react/Routing';
 import { getResourceFromSpec } from '@stainless-api/docs-ui/utils';
 
 import { renderMarkdown } from '@stainless-api/docs-ui/markdown';
@@ -8,6 +8,7 @@ import { renderMarkdown } from '@stainless-api/docs-ui/markdown';
 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';
+import { generateDocsRoutes } from '../helpers/generateDocsRoutes';
 
 type RouteProps = {
   stainlessPath: string;

package/stl-docs/components/mintlify-compat/index.ts

@@ -3,13 +3,11 @@ import Tab from './Tab.astro';
 import Tabs from './Tabs.astro';
 import Frame from './Frame.astro';
 import Columns from './Columns.astro';
-import Steps from './Steps.astro';
-import Step from './Step.astro';
 import Accordion from './Accordion.astro';
 import AccordionGroup from './AccordionGroup.astro';
 
 export * from './callouts';
 export * from './Card';
 
-export { Tab, Tabs, Frame, Columns, Steps, Step, AccordionGroup, Accordion };
-export { Button } from '@stainless-api/ui-primitives';
+export { Tab, Tabs, Frame, Columns, AccordionGroup, Accordion };
+export { Button, Steps, Step } from '@stainless-api/ui-primitives';

package/stl-docs/index.ts

@@ -1,7 +1,6 @@
 import starlight from '@astrojs/starlight';
 import react from '@astrojs/react';
 import type { StarlightPlugin } from '@astrojs/starlight/types';
-import { stainlessStarlight } from '../plugin';
 import { disableCalloutSyntaxStarlightPlugin } from './disableCalloutSyntax';
 
 import type { AstroIntegration } from 'astro';
@@ -22,7 +21,8 @@ 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 { stainlessDocsProseIndexing } from './proseSearchIndexing';
+import { stainlessDocsAlgoliaProseIndexing, stainlessDocsVectorProseIndexing } from './proseSearchIndexing';
+import { stainlessStarlight } from '../plugin';
 
 export * from '../plugin';
 
@@ -244,7 +244,7 @@ function sharedLoggerIntegration(): AstroIntegration {
   };
 }
 
-export function stainlessDocs(config: StainlessDocsUserConfig) {
+export function stainlessDocs(config: StainlessDocsUserConfig): StarlightPlugin[] {
   const normalizedConfigResult = parseStlDocsConfig(config);
   if (normalizedConfigResult.result === 'error') {
     // TODO: would be good to use the astro logger somehow
@@ -271,6 +271,7 @@ export function stainlessDocs(config: StainlessDocsUserConfig) {
       enabled: normalizedConfig.enableProseMarkdownRendering,
       apiReferenceBasePath,
     }),
-    stainlessDocsProseIndexing({ apiReferenceBasePath }),
+    stainlessDocsAlgoliaProseIndexing({ apiReferenceBasePath }),
+    stainlessDocsVectorProseIndexing(normalizedConfig, apiReferenceBasePath),
   ];
 }

package/stl-docs/loadStlDocsConfig.ts

@@ -40,7 +40,7 @@ type ExperimentalStarlightCompatibilityConfig = Pick<
   'components' | 'routeMiddleware' | 'plugins'
 >;
 
-type Tabs = {
+export type Tabs = {
   label: string;
   link: string;
   sidebar?: SidebarEntry[];

package/stl-docs/proseSearchIndexing.ts

@@ -3,8 +3,10 @@ import { readFile } from 'fs/promises';
 import { getProsePages } from '../shared/getProsePages';
 import { getSharedLogger } from '../shared/getSharedLogger';
 import { bold } from '../shared/terminalUtils';
-import { buildProseIndex } from '@stainless-api/docs-search/providers/algolia';
 import * as cheerio from 'cheerio';
+import { toMarkdown } from './proseMarkdown/toMarkdown';
+import { NormalizedStainlessDocsConfig } from './loadStlDocsConfig';
+import { buildProseIndex } from '@stainless-api/docs-search/providers/algolia';
 
 interface ContentBlock {
   type: 'header' | 'content';
@@ -307,7 +309,7 @@ export function* indexHTML(content: string, root: string, pattern: string) {
 const root = 'main';
 const pattern = 'h1, h2, h3, h4, h5, h6, p, li';
 
-export function stainlessDocsProseIndexing({
+export function stainlessDocsAlgoliaProseIndexing({
   apiReferenceBasePath,
 }: {
   apiReferenceBasePath: string | null;
@@ -331,7 +333,7 @@ export function stainlessDocsProseIndexing({
         }
 
         const pagesToRender = await getProsePages({ apiReferenceBasePath, outputBasePath });
-        logger.info(bold(`Indexing ${pagesToRender.length} prose pages for search`));
+        logger.info(bold(`Indexing ${pagesToRender.length} prose pages for algolia search`));
 
         const objects = [];
         for (const absHtmlPath of pagesToRender) {
@@ -353,3 +355,96 @@ export function stainlessDocsProseIndexing({
     },
   };
 }
+
+export function stainlessDocsVectorProseIndexing(
+  config: NormalizedStainlessDocsConfig,
+  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 stainlessProjectName = config.apiReference?.stainlessProject;
+
+        const {
+          STAINLESS_API_KEY: stainlessApiKey,
+          STAINLESS_DOCS_SITE_ID: stainlessDocsSiteId,
+          STAINLESS_DOCS_REPO_SHA: stainlessDocsRepoSha,
+        } = process.env;
+
+        // Skip indexing if required environment variables are not set
+        if (!stainlessApiKey || !stainlessProjectName || !stainlessDocsSiteId || !stainlessDocsRepoSha) {
+          logger.info(
+            `Skipping vector prose search indexing: required environment/config variables not set, missing: ${[
+              !stainlessApiKey && 'STAINLESS_API_KEY',
+              !stainlessDocsSiteId && 'STAINLESS_DOCS_SITE_ID',
+              !stainlessDocsRepoSha && 'STAINLESS_DOCS_REPO_SHA',
+              !stainlessProjectName && 'stainlessProject in apiReference config',
+            ]
+              .filter(Boolean)
+              .join(', ')}`,
+          );
+          return;
+        }
+
+        const pagesToRender = await getProsePages({ apiReferenceBasePath, outputBasePath });
+
+        if (pagesToRender.length === 0) {
+          logger.info('No prose pages found to index for vector search');
+          return;
+        }
+
+        logger.info(bold(`Indexing ${pagesToRender.length} prose pages for vector search`));
+
+        const objects: {
+          id: string;
+          tag: string;
+          content: string;
+          kind: 'prose';
+          source: string;
+        }[] = [];
+        for (const absHtmlPath of pagesToRender) {
+          const content = await readFile(absHtmlPath, 'utf-8');
+          const markdown = await toMarkdown(content);
+
+          if (markdown) {
+            const idx = indexMarkdown(markdown);
+            for (const { chunk, ...entry } of idx)
+              objects.push({
+                ...entry,
+                kind: 'prose',
+                source: absHtmlPath.slice(outputBasePath.length),
+              });
+          }
+        }
+
+        if (objects.length === 0) {
+          logger.info('No prose content extracted to index for vector search');
+          return;
+        }
+
+        logger.info(bold(`Uploading ${objects.length} prose content chunks to stainless docs index`));
+
+        const response = await fetch(
+          `https://api.stainless.com/api/projects/${stainlessProjectName}/docs-sites/${stainlessDocsSiteId}/index`,
+          {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+              Authorization: `Bearer ${stainlessApiKey}`,
+            },
+            body: JSON.stringify({
+              docs_repo_sha: stainlessDocsRepoSha,
+              index: objects,
+            }),
+          },
+        );
+
+        console.log(`docs index API response code ${response.status}: ${await response.text()}`);
+      },
+    },
+  };
+}

package/styles/search.css

@@ -57,8 +57,6 @@ site-search {
   site-search {
     > button {
       border-radius: var(--sl-button-border-radius);
-      padding-inline-start: var(--sl-button-padding-x);
-      padding-inline-end: var(--sl-button-padding-x);
       width: 100%;
       max-width: 30rem;
       justify-content: start;

package/virtual-module.d.ts

@@ -6,10 +6,11 @@ declare module 'virtual:stl-starlight-virtual-module' {
   import type { CreateShikiHighlighterOptions } from '@astrojs/markdown-remark';
   import type { PropertySettingsType } from '@stainless-api/docs-ui/contexts';
   import type { StlStarlightMiddleware } from '@stainless-api/docs/plugin/MiddlewareTypes';
+  import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
 
   export const BASE_PATH: string;
   export const CMS_PORT: number;
-  export const EXCLUDE_LANGUAGES: string[];
+  export const EXCLUDE_LANGUAGES: DocsLanguage[];
   export const DEFAULT_LANGUAGE: string;
   export const BREADCRUMB_CONFIG: {
     includeCurrentPage?: boolean;

package/stl-docs/components/mintlify-compat/Step.astro

@@ -1,56 +0,0 @@
----
-export interface Props {
-  title?: string;
-}
-
-const { title } = Astro.props;
----
-
-<li class="stl-ui-mintlify-compat-step" data-stl-ui-element>
-  <div class="stl-ui-mintlify-compat-step-step-number"></div>
-  <div>
-    <p class="stl-ui-mintlify-compat-step-title">{title}</p>
-    <div class="stl-ui-mintlify-compat-step-content"><slot /></div>
-  </div>
-</li>
-
-<style>
-  .stl-ui-mintlify-compat-step {
-    display: flex;
-
-    &:not(:first-child) {
-      margin-top: 1rem;
-    }
-  }
-
-  .stl-ui-mintlify-compat-step-step-number {
-    margin-right: 1rem;
-    display: flex;
-    align-items: top;
-    justify-content: center;
-    margin-top: 4px;
-
-    &::before {
-      counter-increment: ui-steps;
-      content: counter(ui-steps);
-      border-radius: 50%;
-      height: 1.5rem;
-      width: 1.5rem;
-      font-size: 0.8rem;
-      color: var(--stl-color-foreground);
-      font-weight: 600;
-      background-color: var(--stl-color-faint-background);
-      display: flex;
-      align-items: center;
-      justify-content: center;
-    }
-  }
-
-  .stl-ui-mintlify-compat-step-title {
-    font-weight: 600;
-    color: var(--stl-color-foreground);
-  }
-  .stl-ui-mintlify-compat-step-content {
-    margin-top: 0.5rem;
-  }
-</style>

package/stl-docs/components/mintlify-compat/Steps.astro

@@ -1,15 +0,0 @@
-<ol class="stl-ui-mintlify-compat-steps"><slot /></ol>
-
-<style>
-  .stl-ui-mintlify-compat-steps {
-    counter-reset: ui-steps;
-    list-style: none;
-    margin: 0;
-    padding: 0;
-    margin-top: 1rem;
-
-    * {
-      margin: 0;
-    }
-  }
-</style>