@stainless-api/docs 0.1.0-beta.125 → 0.1.0-beta.126

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @stainless-api/docs
 
+## 0.1.0-beta.126
+
+### Patch Changes
+
+- 992a07a: Update vendored preview worker
+- 1d1fa35: Use astro remark instead of `marked` to process api reference markdown
+- Updated dependencies [374c0e4]
+  - @stainless-api/ui-primitives@0.1.0-beta.51
+  - @stainless-api/docs-ui@0.1.0-beta.90
+  - @stainless-api/docs-search@0.1.0-beta.43
+
 ## 0.1.0-beta.125
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.125",
+  "version": "0.1.0-beta.126",
   "publishConfig": {
     "access": "public"
   },
@@ -41,15 +41,15 @@
     "vite": ">=7.3.1"
   },
   "dependencies": {
-    "@astrojs/markdown-remark": "^7.0.1",
-    "@astrojs/react": "^5.0.1",
+    "@astrojs/markdown-remark": "^7.1.0",
+    "@astrojs/react": "^5.0.2",
+    "@markdoc/markdoc": "^0.5.6",
     "@stainless-api/sdk": "0.5.0",
     "astro-expressive-code": "^0.41.7",
     "cheerio": "^1.2.0",
     "clsx": "^2.1.1",
     "dotenv": "17.3.1",
     "lucide-react": "^0.577.0",
-    "marked": "^17.0.5",
     "node-html-parser": "^7.1.0",
     "rehype-parse": "^9.0.1",
     "rehype-remark": "^10.0.1",
@@ -61,13 +61,12 @@
     "vite-plugin-prebundle-workers": "^0.2.0",
     "web-worker": "^1.5.0",
     "yaml": "^2.8.3",
-    "@stainless-api/docs-search": "0.1.0-beta.42",
-    "@stainless-api/docs-ui": "0.1.0-beta.89",
-    "@stainless-api/ui-primitives": "0.1.0-beta.50"
+    "@stainless-api/docs-search": "0.1.0-beta.43",
+    "@stainless-api/docs-ui": "0.1.0-beta.90",
+    "@stainless-api/ui-primitives": "0.1.0-beta.51"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.8",
-    "@markdoc/markdoc": "^0.5.6",
     "@types/node": "24.12.0",
     "@types/react": "19.2.14",
     "@types/react-dom": "^19.2.3",

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;
+export 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/react/Routing.tsx

@@ -1,18 +1,13 @@
 import * as React from 'react';
-import { marked, Tokens } from 'marked';
 import { getDocsLanguages } from '../helpers/multiSpec';
 
-import {
-  createMarkdownProcessor,
-  CreateShikiHighlighterOptions,
-  type MarkdownProcessor,
-} from '@astrojs/markdown-remark';
-import remarkGfmAlerts from 'remark-github-alerts';
+import { astroMarkdownRenderText } from '../markdown';
+import { highlight } from '../markdown/highlighter';
 
 import type { MarkdownHeading } from 'astro';
 import type { StarlightRouteData } from '@astrojs/starlight/route-data';
 import type * as SDKJSON from '@stainless/sdk-json';
-import { LanguageNames, SupportedLanguageSyntaxes, type DocsLanguage } from '@stainless-api/docs-ui/routing';
+import { LanguageNames, type DocsLanguage } from '@stainless-api/docs-ui/routing';
 
 import {
   generateRoute,
@@ -46,7 +41,6 @@ import { Dropdown } from '@stainless-api/docs/components';
 import {
   RESOLVED_API_REFERENCE_PATH,
   EXPAND_RESOURCES,
-  HIGHLIGHT_THEMES,
   BREADCRUMB_CONFIG,
   PROPERTY_SETTINGS,
   ENABLE_CONTEXT_MENU,
@@ -54,7 +48,6 @@ import {
   MIDDLEWARE,
 } from 'virtual:stl-starlight-virtual-module';
 import style from '@stainless-api/docs-ui/style';
-import { BundledTheme, createHighlighter, HighlighterGeneric, type BundledLanguage } from 'shiki';
 import {
   SnippetCode,
   SnippetContainer,
@@ -138,58 +131,6 @@ export function buildPageNavigation(resource: SDKJSON.Resource, depth: number =
   return [...output, ...subs];
 }
 
-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;
-}
-
-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: _themes || {},
-  });
-}
-
-async function highlight(content: string, language?: string) {
-  const highlighter = await astroHighlight();
-  return shikiHighlight({ highlighter, content, language });
-}
-
 export function SDKSelectReactComponent({
   selected,
   languages,
@@ -295,7 +236,7 @@ export function RenderSpecOverview({ spec, language }: { spec: SDKJSON.Spec; lan
     <DocsProvider spec={spec} language={language ?? 'node'}>
       <ComponentProvider components={componentOverrides}>
         <NavigationProvider basePath={RESOLVED_API_REFERENCE_PATH}>
-          <MarkdownProvider render={renderMarkdown} highlight={highlight}>
+          <MarkdownProvider render={astroMarkdownRenderText} highlight={highlight}>
             <div className={style.Overview}>
               {resources
                 .filter(({ resource }) => !resource.name.startsWith('$'))
@@ -351,7 +292,7 @@ export function RenderSpec({
     >
       <ComponentProvider components={componentOverrides}>
         <NavigationProvider basePath={RESOLVED_API_REFERENCE_PATH} selectedPath={path}>
-          <MarkdownProvider render={renderMarkdown} highlight={highlight}>
+          <MarkdownProvider render={astroMarkdownRenderText} highlight={highlight}>
             {
               <div className="stldocs-root stl-ui-not-prose">
                 <div className="stl-page-nav-container">
@@ -412,96 +353,3 @@ 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: [
-      HIGHLIGHT_THEMES?.dark ?? 'github-dark',
-      HIGHLIGHT_THEMES?.light ?? 'github-light',
-      {
-        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)' },
-          },
-        ],
-      },
-    ],
-    langs: SupportedLanguageSyntaxes,
-  });
-
-  return astroShikiHighlighter;
-}
-
-// Astro's markdown processor is a singleton
-// Need to cache it instead of instantiating per request
-let astroMarkdownProcessor: MarkdownProcessor;
-async function astroMarkdown() {
-  if (!astroMarkdownProcessor) {
-    astroMarkdownProcessor = await createMarkdownProcessor({
-      gfm: true,
-      remarkPlugins: [remarkGfmAlerts],
-      shikiConfig: {
-        themes: HIGHLIGHT_THEMES,
-      },
-    });
-  }
-
-  return astroMarkdownProcessor;
-}
-
-export async function astroMarkdownRender(content: string) {
-  const md = await astroMarkdown();
-  const output = await md.render(content);
-
-  // Map GFM callouts to the closest Starlight equivalent
-  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;
-}

package/plugin/routes/Docs.astro

@@ -1,6 +1,7 @@
 ---
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
-import { getReadmeContent, buildPageNavigation, RenderSpec, astroMarkdownRender } from '../react/Routing';
+import { getReadmeContent, buildPageNavigation, RenderSpec } from '../react/Routing';
+import { astroMarkdownRender } from '../markdown';
 import { getResourceFromSpec } from '@stainless-api/docs-ui/utils';
 import { parseRoute, parseStainlessPath } from '@stainless-api/docs-ui/routing';
 import {