@stainless-api/docs 0.1.0-beta.98 → 1.0.0-beta.140

package/plugin/loadPluginConfig.ts

@@ -5,20 +5,22 @@ import { existsSync, readFileSync } from 'fs';
 import type { CreateShikiHighlighterOptions } from '@astrojs/markdown-remark';
 import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
 import type { PropertySettingsType } from '@stainless-api/docs-ui/contexts';
-import { bold } from '../shared/terminalUtils';
-import { resolveSpec, SpecInputResolver } from './specs/inputResolver';
-import { specCache, SpecCacheResult } from './specs/generateSpec';
 
-export type LanguageGenerateQuery = {
-  mode: 'exclude' | 'only';
-  list: DocsLanguage[];
+import { defaultSpecLoader } from './specs/defaultSpecLoader';
+import { SpecLoaderFn } from './specs/utils';
+
+type ApiKeySource = 'explicit-config' | 'environment-variable' | 'cli';
+
+type LoadedApiKey = {
+  value: string;
+  source: ApiKeySource;
 };
 
-export type AstroCommand = 'dev' | 'build' | 'preview' | 'sync';
+type AstroCommand = 'dev' | 'build' | 'preview' | 'sync';
 
-export type ContentLayout = 'double-pane' | 'single-pane';
+type ContentLayout = 'double-pane' | 'single-pane';
 
-export type VersionUserConfig = {
+type VersionUserConfig = {
   version: string;
   stainlessProject: string;
   branch: string;
@@ -50,17 +52,9 @@ export type StainlessStarlightUserConfig = {
   stainlessProject: string;
 
   /**
-   * Powerful configuration options for customized use cases
+   * Optional function to provide your own loader for API reference data.
    */
-  advanced?: {
-    /**
-     *
-     * More advanced replacement for versions, basePath, and excludeLanguages.
-     */
-    overrideSpecs?: {
-      specs: SpecInputResolver[];
-    };
-  };
+  loadSpecs?: SpecLoaderFn;
 
   /**
    * Optional list of versions to render in the API reference.
@@ -149,13 +143,7 @@ export type StainlessStarlightUserConfig = {
    * @default true
    */
 
-  contextMenu?: boolean;
-
-  /**
-   * When set to `import playgrounds from '@stainless-api/playgrounds'`, code snippets will have a "Play" button,
-   * allowing users to edit and run code snippets in their browser.
-   */
-  experimentalPlaygrounds?: { playgroundsBase: string };
+  contextMenu?: boolean | { thirdParty?: boolean };
 
   /** When set to true, enables the experimental request builder interface for testing API endpoints. */
   experimentalRequestBuilder?: boolean;
@@ -165,6 +153,31 @@ export type StainlessStarlightUserConfig = {
    * @default true
    */
   experimentalPrerender?: boolean;
+
+  /**
+   * Configuration for the generated `/llms.txt` file.
+   */
+  llmsTxt?: {
+    /**
+     * Whether to disable the generated `/llms.txt` file.
+     *
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * A short description of the site, used as the blockquote summary at the top of the file.
+     * Falls back to the top-level Starlight `description` field if not set.
+     */
+    description?: string;
+    /**
+     * The maximum number of total routes (prose + API reference) at which the file switches
+     * from compact mode (resources only) to detailed mode (resources and
+     * methods).
+     *
+     * @default 2000
+     */
+    detailThreshold?: number;
+  };
 };
 
 // TODO: eventually? re-add support for external spec servers
@@ -174,37 +187,6 @@ export type StainlessStarlightUserConfig = {
 
 export type SomeStainlessStarlightUserConfig = StainlessStarlightUserConfig;
 
-function resolvePath(inputPath: string) {
-  return path.resolve(process.cwd(), inputPath);
-}
-
-function getLocalFilePaths(command: AstroCommand) {
-  if (command !== 'dev') {
-    return null;
-  }
-
-  // eslint-disable-next-line turbo/no-undeclared-env-vars
-  const oasPath = process.env.OPENAPI_PATH;
-  // eslint-disable-next-line turbo/no-undeclared-env-vars
-  const configPath = process.env.STAINLESS_CONFIG_PATH;
-
-  if (!oasPath || !configPath) {
-    return null;
-  }
-
-  return {
-    oasPath: resolvePath(oasPath),
-    configPath: resolvePath(configPath),
-  };
-}
-
-export type ApiKeySource = 'explicit-config' | 'environment-variable' | 'cli';
-
-export type LoadedApiKey = {
-  value: string;
-  source: ApiKeySource;
-};
-
 function parseAuthJson(authJsonStr: string) {
   let json: unknown;
   try {
@@ -252,6 +234,7 @@ function loadApiKey(configValue: string | undefined): LoadedApiKey | null {
   return { value: accessToken, source: 'cli' };
 }
 
+/** @public but discouraged - used by cloudflare via relative import */
 export function forceLoadStainlessCredentials(): LoadedApiKey {
   const v = loadApiKey(undefined);
   if (!v) {
@@ -265,99 +248,11 @@ type AstroOptions = {
   base: string;
 };
 
-export type ResolvedAPIConfigEntry = {
-  loadSpecs: () => Promise<SpecCacheResult[]>;
-};
-
-function makeSimpleAPIConfig(
-  partial: SomeStainlessStarlightUserConfig,
-  astroOptions: AstroOptions,
-): ResolvedAPIConfigEntry {
-  if (!('stainlessProject' in partial)) {
-    throw new Error('You must provide a stainlessProject when using Stainless Starlight');
-  }
-
-  const excludedLanguages = ['php' as const, ...(partial.excludeLanguages ?? [])];
-
-  const apiKey = loadApiKey(partial.apiKey);
-
-  function getResolver() {
-    const localFilePaths = getLocalFilePaths(astroOptions.command);
-    if (localFilePaths) {
-      return resolveSpec.fromFiles({
-        oasPath: localFilePaths.oasPath,
-        configPath: localFilePaths.configPath,
-        languageOverrides: {
-          mode: 'exclude',
-          list: excludedLanguages,
-        },
-        stainlessProject: partial.stainlessProject,
-      });
-    }
-
-    if (!apiKey) {
-      throw new Error(
-        [
-          bold(
-            'No Stainless credentials found. Please choose one of the following options to authenticate with Stainless:',
-          ),
-          '- Run `stl auth login` to authenticate via the Stainless CLI',
-          '- Provide a Stainless API key via the `STAINLESS_API_KEY` environment variable (eg. in a .env file)',
-          '- Set the `apiKey` option in the Stainless Docs config',
-        ].join('\n'),
-      );
-    }
-    return resolveSpec.fromStainlessApi({
-      stainlessProject: partial.stainlessProject,
-      branch: partial.versions?.[0]?.branch ?? 'main',
-      apiKey: apiKey,
-      languageOverrides: {
-        mode: 'exclude',
-        list: excludedLanguages,
-      },
-    });
-  }
-
-  const resolver = getResolver();
-
-  return {
-    loadSpecs: async function loadSpecs() {
-      const inputs = await resolver.resolve({ apiKey });
-
-      const result = await specCache.get(inputs);
-
-      return [result];
-    },
-  };
-}
-
-function loadAPIConfig(
-  partial: SomeStainlessStarlightUserConfig,
-  astroOptions: AstroOptions,
-): ResolvedAPIConfigEntry {
-  if (partial.advanced?.overrideSpecs) {
-    const overrides = partial.advanced.overrideSpecs;
-    const apiKey = loadApiKey(partial.apiKey);
-    return {
-      loadSpecs: async function loadSpecs() {
-        const specsPromises = overrides.specs.map(async (spec) => {
-          const inputs = await spec.resolve({ apiKey });
-          return await specCache.get(inputs);
-        });
-
-        return await Promise.all(specsPromises);
-      },
-    };
-  }
-  return makeSimpleAPIConfig(partial, astroOptions);
-}
-
 function normalizeConfig(partial: SomeStainlessStarlightUserConfig, astroOptions: AstroOptions) {
   const configWithDefaults = {
     basePath: partial.basePath ?? '/api',
     astroBase: astroOptions.base,
-    // TODO: why are we excluding php; do we need to
-    excludeLanguages: ['php' as const, ...(partial.excludeLanguages ?? [])],
+    excludeLanguages: partial.excludeLanguages ?? [],
     defaultLanguage: partial.defaultLanguage ?? 'http',
     breadcrumbs: {
       includeCurrentPage: partial.breadcrumbs?.includeCurrentPage ?? false,
@@ -382,18 +277,20 @@ function normalizeConfig(partial: SomeStainlessStarlightUserConfig, astroOptions
       includeModelProperties: partial.propertySettings?.includeModelProperties ?? true,
     },
     contextMenu: partial.contextMenu ?? true,
-    experimentalPlaygrounds: partial.experimentalPlaygrounds ?? undefined,
     experimentalRequestBuilder: partial.experimentalRequestBuilder ?? false,
     experimentalPrerender: partial.experimentalPrerender ?? true,
     stainlessProject: partial.stainlessProject,
+    llmsTxt: {
+      enabled: !partial.llmsTxt?.disabled,
+      description: partial.llmsTxt?.description ?? null,
+      detailThreshold: partial.llmsTxt?.detailThreshold ?? 2000,
+    },
+    apiKey: loadApiKey(partial.apiKey),
+    loadSpecs: partial.loadSpecs ?? defaultSpecLoader,
+    branch: partial.versions?.[0]?.branch ?? 'main',
   };
 
-  const api = loadAPIConfig(partial, astroOptions);
-
-  return {
-    ...configWithDefaults,
-    api,
-  };
+  return configWithDefaults;
 }
 
 export type NormalizedStainlessStarlightConfig = ReturnType<typeof normalizeConfig>;

package/plugin/markdown/highlighter.ts

@@ -0,0 +1,100 @@
+import {
+  createHighlighter,
+  type HighlighterGeneric,
+  type ThemeInput,
+  type BundledTheme,
+  type BundledLanguage,
+} from 'shiki';
+import { HIGHLIGHT_THEMES } from 'virtual:stl-starlight-virtual-module';
+import { SupportedLanguageSyntaxes } from '@stainless-api/docs-ui/routing';
+import type { CreateShikiHighlighterOptions } from '@astrojs/markdown-remark';
+
+const STAINLESS_DOCS_JSON_THEME = {
+  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-orange-foreground)' },
+    },
+    // strings
+    {
+      scope: ['string', 'string.quoted', 'string.template'],
+      settings: { foreground: 'var(--stl-color-green-foreground)' },
+    },
+    // 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-purple-foreground)' },
+    },
+  ],
+} satisfies ThemeInput;
+
+// singleton
+let astroShikiHighlighter:
+  | HighlighterGeneric<BundledLanguage, BundledTheme>
+  | Promise<HighlighterGeneric<BundledLanguage, BundledTheme>>
+  | null = null;
+async function getAstroHighlighter() {
+  if (astroShikiHighlighter) {
+    return astroShikiHighlighter;
+  }
+
+  astroShikiHighlighter = createHighlighter({
+    themes: [
+      HIGHLIGHT_THEMES?.dark ?? 'github-dark',
+      HIGHLIGHT_THEMES?.light ?? 'github-light',
+      STAINLESS_DOCS_JSON_THEME,
+    ],
+    langs: SupportedLanguageSyntaxes,
+  });
+
+  return astroShikiHighlighter;
+}
+
+function runHighlight({
+  highlighter,
+  content,
+  language,
+  themes,
+}: {
+  highlighter: HighlighterGeneric<BundledLanguage, BundledTheme>;
+  content: string;
+  language?: string;
+  themes?: CreateShikiHighlighterOptions['themes'] | Record<string, 'stainless-docs-json'>;
+}) {
+  return highlighter.codeToHtml(content, {
+    lang: language ?? 'javascript',
+    themes:
+      // Default to user-provided themes except in case of json
+      themes ??
+      (language === 'JSON'
+        ? { light: 'stainless-docs-json', dark: 'stainless-docs-json' }
+        : HIGHLIGHT_THEMES) ??
+      {},
+  });
+}
+
+export async function highlight(content: string, language?: string) {
+  const highlighter = await getAstroHighlighter();
+  return runHighlight({ highlighter, content, language });
+}

package/plugin/markdown/index.ts

@@ -0,0 +1,39 @@
+import { createMarkdownProcessor, type MarkdownProcessor } from '@astrojs/markdown-remark';
+import remarkGfmAlerts from 'remark-github-alerts';
+import { HIGHLIGHT_THEMES } from 'virtual:stl-starlight-virtual-module';
+
+// singleton
+let astroMarkdownProcessor: MarkdownProcessor;
+async function getAstroMarkdown() {
+  if (!astroMarkdownProcessor) {
+    astroMarkdownProcessor = await createMarkdownProcessor({
+      gfm: true,
+      remarkPlugins: [remarkGfmAlerts],
+      shikiConfig: { themes: HIGHLIGHT_THEMES },
+    });
+  }
+
+  return astroMarkdownProcessor;
+}
+
+export async function astroMarkdownRender(content: string) {
+  const md = await getAstroMarkdown();
+  const output = await md.render(content);
+
+  // Map GFM callouts to the closest Starlight equivalent
+  // TODO: this sucks; we should be rendering via ui-primitives callouts instead of ugly theme-incompatible starlight ones
+  output.code = output.code
+    .replaceAll('markdown-alert-caution', 'markdown-alert-danger')
+    .replaceAll('markdown-alert-warning', 'markdown-alert-caution')
+    .replaceAll('markdown-alert-important', 'markdown-alert-caution')
+    .replaceAll('markdown-alert-title', 'starlight-aside__title')
+    .replaceAll('markdown-alert-', 'starlight-aside--')
+    .replaceAll('markdown-alert', 'starlight-aside');
+
+  return output;
+}
+
+export async function astroMarkdownRenderText(content: string) {
+  const result = await astroMarkdownRender(content);
+  return result.code;
+}

package/plugin/middlewareBuilder/stainlessMiddleware.d.ts

@@ -1,5 +1,7 @@
 import type { TransformRequestSnippetFn } from '@stainless-api/docs-ui/components/sdk';
+import type { AppComponents } from '@stainless-api/docs-ui/contexts/component';
 
 export type StlStarlightMiddleware = {
   transformRequestSnippet?: TransformRequestSnippetFn;
+  componentOverrides?: Partial<AppComponents>;
 };