@stainless-api/docs 0.1.0-beta.83 → 0.1.0-beta.85

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @stainless-api/docs
 
+## 0.1.0-beta.85
+
+### Patch Changes
+
+- 4b1a91d: pagefind-ignore for breadcrumbs & ai dropdown
+- Updated dependencies [274cefc]
+  - @stainless-api/docs-ui@0.1.0-beta.63
+  - @stainless-api/docs-search@0.1.0-beta.16
+
+## 0.1.0-beta.84
+
+### Minor Changes
+
+- 6ef241e: Sidebar improvements; rename Sidebar to SDKSidebar
+
+### Patch Changes
+
+- d3a85b5: feat: improve not implemented fallback ui
+- 5156697: include markdown alt link for all pages
+- dedd93b: fix incorrect link rel=alternate markdown URLs
+- b532d45: use method summary as page title
+- Updated dependencies [6ef241e]
+- Updated dependencies [d3a85b5]
+- Updated dependencies [d3a85b5]
+- Updated dependencies [2dcb5fb]
+  - @stainless-api/docs-ui@0.1.0-beta.62
+  - @stainless-api/docs-search@0.1.0-beta.15
+
 ## 0.1.0-beta.83
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.83",
+  "version": "0.1.0-beta.85",
   "publishConfig": {
     "access": "public"
   },
@@ -30,7 +30,7 @@
     "node": ">=18.17.1"
   },
   "peerDependencies": {
-    "@astrojs/starlight": ">=0.37.0",
+    "@astrojs/starlight": ">=0.37.4",
     "astro": ">=5.15.3",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
@@ -58,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.14",
-    "@stainless-api/docs-ui": "0.1.0-beta.61",
+    "@stainless-api/docs-search": "0.1.0-beta.16",
+    "@stainless-api/docs-ui": "0.1.0-beta.63",
     "@stainless-api/ui-primitives": "0.1.0-beta.45"
   },
   "devDependencies": {

package/plugin/helpers/generateDocsRoutes.ts

@@ -15,7 +15,7 @@ export function generateDocsRoutes(spec: SDKJSON.Spec, excludeLanguages: DocsLan
       stainlessPath: null,
       language: language as DocsLanguage,
       title: 'Readme',
-      kind: 'readme',
+      kind: 'readme' as const,
     }));
 
   return [...paths, ...readmes].map(({ slug, stainlessPath, language, title, kind }) => {

package/plugin/index.ts

@@ -30,6 +30,7 @@ import { resolveSrcFile } from '../resolveSrcFile';
 import { mkdir, writeFile } from 'fs/promises';
 import { fileURLToPath } from 'url';
 import prebundleWorkers from 'vite-plugin-prebundle-workers';
+import { generateMissingRouteList } from '@stainless-api/docs-ui/routing';
 
 export { generateAPILink } from './generateAPIReferenceLink';
 export type { ReferenceSidebarConfigItem };
@@ -377,6 +378,31 @@ async function stlStarlightAstroIntegration(
           astroBase,
         };
         await writeFile(path.join(stainlessDir, 'stl-manifest.json'), JSON.stringify(manifest, null, 2));
+
+        // Generate a list of missing API routes to enable graceful handling of unimplemented SDK methods.
+        // When users switch languages in the docs, some API methods may not be implemented in the target SDK.
+        // Instead of showing a generic 404, we statically generate pages for these routes and mark them
+        // in this file so Cloudflare can serve them with a 404 status. These pages display helpful information
+        // about the missing method and provide links to SDKs where it is available.
+        const { data: spec } = (await (
+          await fetch(`http://localhost:${CMS_PORT}/retrieve_spec`, {
+            method: 'POST',
+            body: JSON.stringify({}),
+          })
+        ).json()) as SpecResp;
+        if (spec) {
+          const missingRoutes = await generateMissingRouteList({
+            spec,
+            basePath: path.posix.join(astroBase, pluginConfig.basePath),
+          });
+          await mkdir(stainlessDir, { recursive: true });
+          await writeFile(
+            path.join(stainlessDir, 'missing-routes.json'),
+            JSON.stringify(missingRoutes, null, 2),
+          );
+        } else {
+          console.log('Could not retrieve spec for missing routes check');
+        }
       },
     },
   };
@@ -409,6 +435,7 @@ export function stainlessStarlight(someUserConfig: SomeStainlessStarlightUserCon
           }
           process.exit(1);
         }
+
         const config = configParseResult.config;
 
         const isReactLoaded = astroConfig.integrations.find(({ name }) => name === '@astrojs/react');

package/plugin/routes/Docs.astro

@@ -3,8 +3,8 @@ import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
 import { cmsClient } from '../cms/client';
 import { getReadmeContent, buildPageNavigation, RenderSpec, astroMarkdownRender } from '../react/Routing';
 import { getResourceFromSpec } from '@stainless-api/docs-ui/utils';
+import { parseStainlessPath } from '@stainless-api/docs-ui/routing';
 import {
-  BASE_PATH,
   CONTENT_PANEL_LAYOUT,
   MIDDLEWARE,
   EXPERIMENTAL_REQUEST_BUILDER,
@@ -43,27 +43,28 @@ const pageNav =
 
 Astro.locals.language = props.language;
 
+// Use first heading in README as page title
 if (readme) {
   const repo = spec.metadata?.[props.language]?.code_url;
   readme.code = readme.code.replace(/<a href="(?!(?:https?:\/\/|\/\/))([^"]+)"/g, `<a href="${repo}/$1"`);
   props.title = readme.metadata.headings[0]!.text ?? 'Overview';
 }
+
+// use summary for the page title of method pages
+if (props.kind === 'http_method' && props.stainlessPath) {
+  const parsed = parseStainlessPath(props.stainlessPath);
+  const resource = getResourceFromSpec(props.stainlessPath, spec);
+  if (parsed?.method && resource?.methods[parsed.method]) {
+    const method = resource.methods[parsed.method];
+    props.title = method?.summary ?? method?.title ?? props.title;
+  }
+}
 ---
 
 <StarlightPage
   headings={pageNav}
   frontmatter={{
-    title: props?.title,
-    head: [
-      {
-        tag: 'link',
-        attrs: {
-          rel: 'alternate',
-          type: 'text/markdown',
-          href: `${BASE_PATH}/${Astro.params.slug}.md`,
-        },
-      },
-    ],
+    title: props.title,
     pagefind: false,
     tableOfContents: ['resource', 'readme'].includes(props.kind) ? { maxHeadingLevel: 6 } : false,
   }}

package/plugin/routes/markdown.ts

@@ -55,3 +55,5 @@ export const GET: APIRoute<RouteProps> = async ({ props }) => {
     headers: { 'Content-Type': 'text/plain' },
   });
 };
+
+export const prerender = true;

package/stl-docs/components/Head.astro

@@ -1,14 +1,16 @@
 ---
 import Default from '@astrojs/starlight/components/Head.astro';
-
+import path from 'path';
 // TODO: for users who are overriding the font stack in their own styles, how can we know that and
 // preload their font instead of ours?
 import geistPath from '../../assets/fonts/geist/geist-latin.woff2';
+
+const mdPath = path.posix.join(Astro.url.pathname, 'index.md');
 ---
 
 <Default />
-
 <link rel="preload" as="font" type="font/woff2" crossorigin="anonymous" href={geistPath} />
+<link rel="alternate" type="text/markdown" href={mdPath} />
 
 <script>
   import { wireAIDropdown } from '../../plugin/globalJs/ai-dropdown-options.ts';

package/stl-docs/components/PageTitle.astro

@@ -61,7 +61,7 @@ const shouldRenderDescription = RENDER_PAGE_DESCRIPTIONS;
 {
   skipRenderingStarlightTitle ? null : (
     <>
-      <div class="stl-ui-not-prose stl-page-nav-container stl-prose-page-nav-container">
+      <div class="stl-ui-not-prose stl-page-nav-container stl-prose-page-nav-container" data-pagefind-ignore>
         <ContentBreadcrumbs currentPath={currentPath} sidebarEntry={Astro.locals.starlightRoute.sidebar} />
         {showAIDropdown && <AIDropdown />}
       </div>

package/stl-docs/components/sidebars/BaseSidebar.astro

@@ -1,10 +1,15 @@
 ---
-import Default from '@astrojs/starlight/components/Sidebar.astro';
 import HeaderLinks from '../headers/HeaderLinks.astro';
+import { SidebarWithComponents } from './SidebarWithComponents';
+import SidebarPersister from '@astrojs/starlight/components/SidebarPersister.astro';
+
+const { sidebar } = Astro.locals.starlightRoute;
 ---
 
 <div class="stl-sidebar-header-links">
   <HeaderLinks />
 </div>
 <slot name="sdk-select" />
-<Default><slot /></Default>
+<SidebarPersister>
+  <SidebarWithComponents entries={sidebar} withStarlightRestoration />
+</SidebarPersister>

package/stl-docs/components/sidebars/SidebarWithComponents.tsx

@@ -0,0 +1,10 @@
+import { StlSidebar, StlSidebarProps } from '@stainless-api/docs-ui/components';
+import { ComponentProvider } from '@stainless-api/docs-ui/contexts/component';
+
+export function SidebarWithComponents(props: StlSidebarProps) {
+  return (
+    <ComponentProvider>
+      <StlSidebar {...props} />
+    </ComponentProvider>
+  );
+}

package/styles/page.css

@@ -35,7 +35,9 @@
   /* on desktop, adjust sidebar so that its _text content_ aligns with the page left edge.
    * padding (visible on hover) bleeds out beyond the page left edge, covered by --stl-ui-page-padding-inline */
   .sidebar-pane {
-    margin-inline-start: calc(-1 * (var(--sl-sidebar-pad-x) + var(--stl-sidebar-item-padding-inline)));
+    /* 12px comes from --stl-sidebar-item-padding-inline (which is unfortunately defined deeper than
+    this component). Please keep in sync. */
+    margin-inline-start: calc(-1 * (var(--sl-sidebar-pad-x) + 12px));
   }
 
   .header,

package/styles/sidebar.css

@@ -11,220 +11,10 @@
   }
 }
 
-.sidebar {
-  --stl-sidebar-item-padding-inline: 12px;
-  --stl-sidebar-item-padding-block: 6px;
-  --stl-sidebar-indent: 12px;
-  font-size: var(--stl-typography-scale-sm);
-}
-
 .sidebar-pane {
   border-inline-end: 1px solid var(--stl-color-border-faint);
 }
 
-.sidebar-content {
-  ul,
-  summary {
-    list-style-type: none;
-  }
-
-  /* collapsible sections */
-  details > summary {
-    display: flex;
-    align-items: center;
-    font-weight: 500;
-
-    .caret {
-      margin-left: auto;
-      margin-right: -4px;
-      opacity: 0.65;
-      transition:
-        opacity 0.1s ease-out,
-        transform 0.1s ease-out;
-    }
-  }
-  details[open] > summary .caret {
-    opacity: 1;
-    transform: rotate(90deg);
-  }
-
-  /* list items */
-  summary,
-  li {
-    margin: 0;
-    border-radius: 8px;
-  }
-  summary,
-  li a {
-    cursor: pointer;
-    padding: var(--stl-sidebar-item-padding-block) var(--stl-sidebar-item-padding-inline);
-    &:hover,
-    &[aria-current='page'] {
-      color: var(--stl-color-foreground);
-    }
-  }
-
-  li a {
-    color: var(--stl-color-foreground-reduced);
-    font-weight: 400;
-    display: flex;
-    text-decoration: none;
-    span {
-      font-weight: inherit;
-    }
-
-    &:hover {
-      text-decoration: underline;
-      text-decoration-color: var(--stl-color-foreground-reduced);
-    }
-    &[aria-current='page'] {
-      font-weight: 500;
-    }
-  }
-  li:has(> a:is(:hover, [aria-current='page'])),
-  summary:hover {
-    background-color: var(--stl-color-background-hover);
-  }
-
-  /* nested list items have flat left edge */
-  ul ul :is(summary, li) {
-    border-start-start-radius: 0;
-    border-end-start-radius: 0;
-  }
-  ul {
-    padding: 0;
-  }
-  ul ul li {
-    border-inline-start: 1px solid var(--stl-color-border-faint);
-    margin-inline-start: var(--stl-sidebar-indent);
-    &:has(> a[aria-current='page']) {
-      border-inline-start: 2px solid var(--stl-color-accent-border-strong);
-      & > a {
-        margin-left: -1px;
-      }
-    }
-  }
-
-  /* Method & resource icons */
-
-  a[data-stldocs-method],
-  a[data-stldocs-resource] {
-    --stl-ui-sidebar-icon-size-outer: 18px;
-    --stl-ui-sidebar-icon-margin: 8px;
-  }
-  a[data-stldocs-method] {
-    --stl-ui-sidebar-icon-size-inner: 16px;
-    --stl-ui-sidebar-icon-color-inverse-background: var(--stl-ui-sidebar-icon-color);
-
-    &[data-stldocs-method='get'] {
-      --stl-ui-sidebar-icon-color: var(--stl-color-green-foreground);
-      --stl-ui-sidebar-icon-color-border: var(--stl-color-green-border);
-      --stl-ui-sidebar-icon-color-background: var(--stl-color-green-muted-background);
-      --stl-ui-sidebar-icon-color-background-hover: var(--stl-color-green-muted-background-hover);
-      --stl-ui-sidebar-icon-color-inverse-background: var(--stl-color-green-inverse-background);
-      --stl-ui-sidebar-icon-color-inverse-foreground: var(--stl-color-green-inverse-foreground);
-    }
-    &[data-stldocs-method='post'] {
-      --stl-ui-sidebar-icon-color: var(--stl-color-blue-foreground);
-      --stl-ui-sidebar-icon-color-border: var(--stl-color-blue-border);
-      --stl-ui-sidebar-icon-color-background: var(--stl-color-blue-muted-background);
-      --stl-ui-sidebar-icon-color-background-hover: var(--stl-color-blue-muted-background-hover);
-      --stl-ui-sidebar-icon-color-inverse-background: var(--stl-color-blue-inverse-background);
-      --stl-ui-sidebar-icon-color-inverse-foreground: var(--stl-color-blue-inverse-foreground);
-    }
-    &[data-stldocs-method='patch'],
-    &[data-stldocs-method='put'] {
-      --stl-ui-sidebar-icon-color: var(--stl-color-orange-foreground);
-      --stl-ui-sidebar-icon-color-border: var(--stl-color-orange-border);
-      --stl-ui-sidebar-icon-color-background: var(--stl-color-orange-muted-background);
-      --stl-ui-sidebar-icon-color-background-hover: var(--stl-color-orange-muted-background-hover);
-      --stl-ui-sidebar-icon-color-inverse-background: var(--stl-color-orange-inverse-background);
-      --stl-ui-sidebar-icon-color-inverse-foreground: var(--stl-color-orange-inverse-foreground);
-    }
-    &[data-stldocs-method='delete'] {
-      --stl-ui-sidebar-icon-color: var(--stl-color-red-foreground);
-      --stl-ui-sidebar-icon-color-border: var(--stl-color-red-border);
-      --stl-ui-sidebar-icon-color-background: var(--stl-color-red-muted-background);
-      --stl-ui-sidebar-icon-color-background-hover: var(--stl-color-red-muted-background-hover);
-      --stl-ui-sidebar-icon-color-inverse-background: var(--stl-color-red-inverse-background);
-      --stl-ui-sidebar-icon-color-inverse-foreground: var(--stl-color-red-inverse-foreground);
-    }
-
-    &[data-stldocs-method='get'] {
-      --stl-ui-sidebar-icon-url: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="black" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M17 7 7 17"/><path d="M17 17H7V7"/></svg>');
-    }
-    &[data-stldocs-method='post'],
-    &[data-stldocs-method='put'],
-    &[data-stldocs-method='patch'] {
-      --stl-ui-sidebar-icon-url: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="black" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M7 7h10v10"/><path d="M7 17 17 7"/></svg>');
-    }
-    &[data-stldocs-method='delete'] {
-      --stl-ui-sidebar-icon-url: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="black" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 6 6 18"/><path d="m6 6 12 12"/></svg>');
-    }
-  }
-
-  a[data-stldocs-resource] {
-    /* not yet implemented in markup */
-    --stl-ui-sidebar-icon-color: var(--stl-color-foreground-muted);
-    --stl-ui-sidebar-icon-color-border: var(--stl-color-border);
-    --stl-ui-sidebar-icon-color-background: var(--stl-color-faint-background);
-    --stl-ui-sidebar-icon-color-background-hover: var(--stl-color-faint-background-hover);
-    --stl-ui-sidebar-icon-color-inverse-background: var(--stl-color-inverse-background);
-    --stl-ui-sidebar-icon-color-inverse-foreground: var(--stl-color-inverse-foreground);
-
-    --stl-ui-sidebar-icon-size-inner: 14px;
-    --stl-ui-sidebar-icon-url: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="black" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M8 3H7a2 2 0 0 0-2 2v5a2 2 0 0 1-2 2 2 2 0 0 1 2 2v5c0 1.1.9 2 2 2h1"/><path d="M16 21h1a2 2 0 0 0 2-2v-5c0-1.1.9-2 2-2a2 2 0 0 1-2-2V5a2 2 0 0 0-2-2h-1"/></svg>');
-  }
-
-  a[data-stldocs-method],
-  a[data-stldocs-resource] {
-    display: flex;
-    gap: var(--stl-ui-sidebar-icon-margin);
-    align-items: center;
-    position: relative;
-
-    &::before,
-    &::after {
-      content: '';
-      width: var(--stl-ui-sidebar-icon-size-outer);
-      height: var(--stl-ui-sidebar-icon-size-outer);
-      display: block;
-    }
-    &::before {
-      border-radius: 4px;
-      background-color: var(--stl-ui-sidebar-icon-color-background);
-      flex: 0 0 auto;
-      border: 1px solid var(--stl-ui-sidebar-icon-color-border, transparent);
-    }
-    /* yuck (we can clean this up once we are changing sidebar markup) */
-    &::after {
-      background-color: var(--stl-ui-sidebar-icon-color);
-      mask-image: var(--stl-ui-sidebar-icon-url);
-      mask-size: var(--stl-ui-sidebar-icon-size-inner) var(--stl-ui-sidebar-icon-size-inner);
-      mask-repeat: no-repeat;
-      mask-position: center;
-      position: absolute;
-      left: var(--stl-sidebar-item-padding-inline);
-      top: 50%;
-      transform: translateY(-50%);
-    }
-
-    &:hover {
-      &::before {
-        background-color: var(--stl-ui-sidebar-icon-color-background-hover);
-      }
-    }
-    &[aria-current='page'] {
-      &::before {
-        background-color: var(--stl-ui-sidebar-icon-color-inverse-background);
-      }
-      &::after {
-        background-color: var(--stl-ui-sidebar-icon-color-inverse-foreground);
-      }
-    }
-  }
-}
-
 .sidebar-content .stl-mobile-only-sidebar-item-last {
   margin-bottom: 2rem;
   position: relative;

package/theme.css

@@ -23,3 +23,4 @@
 @import '@stainless-api/docs-ui/styles/primitives.css';
 @import '@stainless-api/docs-ui/styles/main.css';
 @import '@stainless-api/docs-ui/styles/search.css';
+@import '@stainless-api/docs-ui/styles/sidebar.css';