@stainless-api/docs 0.1.0-beta.127 → 0.1.0-beta.129

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @stainless-api/docs
 
+## 0.1.0-beta.129
+
+### Minor Changes
+
+- 966ec34: Fixes nav dropdown logic
+
+### Patch Changes
+
+- Updated dependencies [966ec34]
+  - @stainless-api/ui-primitives@0.1.0-beta.52
+  - @stainless-api/docs-search@0.1.0-beta.45
+  - @stainless-api/docs-ui@0.1.0-beta.92
+
+## 0.1.0-beta.128
+
+### Patch Changes
+
+- e8a95f4: Revert “Fix getProsePages treating all pages as prose when API reference basePath is empty”
+
 ## 0.1.0-beta.127
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.127",
+  "version": "0.1.0-beta.129",
   "publishConfig": {
     "access": "public"
   },
@@ -61,9 +61,9 @@
     "vite-plugin-prebundle-workers": "^0.2.0",
     "web-worker": "^1.5.0",
     "yaml": "^2.8.3",
-    "@stainless-api/docs-search": "0.1.0-beta.44",
-    "@stainless-api/docs-ui": "0.1.0-beta.91",
-    "@stainless-api/ui-primitives": "0.1.0-beta.51"
+    "@stainless-api/docs-search": "0.1.0-beta.45",
+    "@stainless-api/docs-ui": "0.1.0-beta.92",
+    "@stainless-api/ui-primitives": "0.1.0-beta.52"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.8",

package/plugin/index.ts

@@ -30,7 +30,7 @@ import prebundleWorkers from 'vite-plugin-prebundle-workers';
 import { SpecLoader, startSpecLoader } from './specs';
 
 import type * as ReferenceSidebarsVirtualModule from 'virtual:stl-starlight-reference-sidebars';
-import { generateMissingRouteList, generateRouteList } from '@stainless-api/docs-ui/routing';
+import { generateMissingRouteList } from '@stainless-api/docs-ui/routing';
 import { buildAlgoliaIndex } from './buildAlgoliaIndex';
 
 export { generateAPILink } from './generateAPIReferenceLink';
@@ -357,26 +357,13 @@ function stlStarlightAstroIntegration(pluginConfig: NormalizedStainlessStarlight
           collectedErrors = null;
         }
 
-        const specComposite = await resolveSpecs();
-
-        // TODO: (multi-spec) support multiple specs
-        const spec = specComposite.listUniqueSpecs()[0]!.data.sdkJson;
-
-        const basePrefixInOutput = path.posix.join(astroBase, pluginConfig.basePath).replace(/^\/+/, '');
-        const routeList = generateRouteList({ spec });
-        const apiReferencePages = [
-          // overview page
-          path.posix.join(basePrefixInOutput, 'index.html'),
-          // all route pages
-          ...routeList.map((r) => path.posix.join(basePrefixInOutput, r.slug, 'index.html')),
-        ];
-
         const manifest = {
           astroBase,
-          apiReferencePages,
         };
         await writeFile(path.join(stainlessDir, 'stl-manifest.json'), JSON.stringify(manifest, null, 2));
 
+        const specComposite = await resolveSpecs();
+
         await buildAlgoliaIndex({
           specComposite,
           logger,
@@ -388,6 +375,9 @@ function stlStarlightAstroIntegration(pluginConfig: NormalizedStainlessStarlight
         // 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.
 
+        // TODO: (multi-spec) support multiple specs
+        const spec = specComposite.listUniqueSpecs()[0]!.data.sdkJson;
+
         const missingRoutes = generateMissingRouteList({
           spec,
           basePath: path.posix.join(astroBase, pluginConfig.basePath),

package/shared/getProsePages.ts

@@ -1,8 +1,6 @@
-import { readdir, readFile } from 'fs/promises';
+import { readdir } from 'fs/promises';
 import { join, relative } from 'path';
 
-const MANIFEST_PATH = '_stainless/stl-manifest.json';
-
 /**
  * Get all prose pages after a build, by reading all HTML files from the
  * given output directory, and not from assets.
@@ -12,11 +10,14 @@ const MANIFEST_PATH = '_stainless/stl-manifest.json';
  * Other astro integrations may hijack the "[...slug]" entrypoint, and any files
  * previously in the [...slug] asset map entry would be lost (this is where starlight stores
  * its prose HTML files).
- *
- * API reference pages are excluded using the manifest written by the API
- * reference plugin at build time, rather than guessing based on path prefix.
  */
-export async function getProsePages({ outputBasePath }: { outputBasePath: string }): Promise<string[]> {
+export async function getProsePages({
+  apiReferenceBasePath,
+  outputBasePath,
+}: {
+  apiReferenceBasePath: string | null;
+  outputBasePath: string;
+}): Promise<string[]> {
   const allFiles = await readdir(outputBasePath, {
     recursive: true,
     withFileTypes: true,
@@ -26,22 +27,15 @@ export async function getProsePages({ outputBasePath }: { outputBasePath: string
     .filter((file) => file.isFile() && file.name.endsWith('.html'))
     .map((file) => join(file.parentPath, file.name));
 
-  const apiReferencePages = await readApiReferencePagesFromManifest(outputBasePath);
-  if (apiReferencePages.size === 0) return htmlFiles;
-
-  return htmlFiles.filter((absPath) => {
+  if (!apiReferenceBasePath) return htmlFiles;
+  // Normalize by removing leading/trailing slashes from apiReferenceBasePath
+  const normalizedApiPath = apiReferenceBasePath.replace(/^\/+/g, '').replace(/\/+$/g, '');
+  const pagesToRender = htmlFiles.filter((absPath) => {
     const relPath = relative(outputBasePath, absPath);
-    return !apiReferencePages.has(relPath);
+    // Filter out API reference pages
+    if (relPath === normalizedApiPath || relPath.startsWith(`${normalizedApiPath}/`)) return false;
+    return true;
   });
-}
 
-async function readApiReferencePagesFromManifest(outputBasePath: string): Promise<Set<string>> {
-  try {
-    const raw = await readFile(join(outputBasePath, MANIFEST_PATH), 'utf-8');
-    const manifest = JSON.parse(raw) as { apiReferencePages?: string[] };
-    const pages = manifest.apiReferencePages ?? [];
-    return new Set(pages);
-  } catch {
-    return new Set();
-  }
+  return pagesToRender;
 }

package/stl-docs/components/nav-tabs/NavDropdown.astro

@@ -1,29 +1,33 @@
 ---
-import { Dropdown } from '@stainless-api/docs/components';
-import { buildNavLinks } from './buildNavLinks';
 import { ChevronsUpDownIcon } from 'lucide-react';
+import { Dropdown } from '@stainless-api/docs/components';
 
-const navLinks = buildNavLinks(Astro.locals.starlightRoute);
+import type { NavLink } from './buildNavLinks';
 
-const buttonText = (navLinks.find((item) => item.active) ?? navLinks[0]!).label;
+export type Props = {
+  links: NavLink[];
+  currentItem: NavLink | null;
+};
 ---
 
 <Dropdown id="nav-dropdown" className="nav-dropdown-root">
   <Dropdown.Trigger>
-    <Dropdown.TriggerSelectedItem>{buttonText}</Dropdown.TriggerSelectedItem>
+    <Dropdown.TriggerSelectedItem>
+      {Astro.props.currentItem ? Astro.props.currentItem.label : 'Navigation'}
+    </Dropdown.TriggerSelectedItem>
     <Dropdown.TriggerIcon>
       <ChevronsUpDownIcon size={16} />
     </Dropdown.TriggerIcon>
   </Dropdown.Trigger>
   <Dropdown.Menu className="dropdown-menu">
     {
-      navLinks.map((item) => (
+      Astro.props.links.map((item) => (
         <Dropdown.MenuItem
           key={item.link}
           href={item.link}
           className="dropdown-item"
           value={item.label}
-          isSelected={item.label === buttonText}
+          isSelected={item.active}
         >
           {item.label}
           <Dropdown.MenuItemTemplate>{item.label}</Dropdown.MenuItemTemplate>
@@ -39,6 +43,7 @@ const buttonText = (navLinks.find((item) => item.active) ?? navLinks[0]!).label;
 
   document.addEventListener(getPageLoadEvent(), () => {
     initDropdown({
+      initialValue: null,
       root: document.getElementById('nav-dropdown'),
     });
   });

package/stl-docs/components/nav-tabs/NavTabs.astro

@@ -5,6 +5,8 @@ import NavDropdown from './NavDropdown.astro';
 import clsx from 'clsx';
 
 const navLinks = buildNavLinks(Astro.locals.starlightRoute);
+
+const currentItem = navLinks.find((item) => item.active) ?? null;
 ---
 
 <div id="nav-links-container" class="nav-links-container">
@@ -26,7 +28,7 @@ const navLinks = buildNavLinks(Astro.locals.starlightRoute);
     </ul>
   </div>
   <div class="mobile-nav-dropdown" data-mobile-only>
-    <NavDropdown />
+    {navLinks.length > 0 && <NavDropdown links={navLinks} currentItem={currentItem} />}
   </div>
 </div>
 

package/stl-docs/components/nav-tabs/buildNavLinks.ts

@@ -13,3 +13,5 @@ export function buildNavLinks(starlightRoute: StarlightRouteData) {
 
   return navLinks;
 }
+
+export type NavLink = ReturnType<typeof buildNavLinks>[number];

package/stl-docs/index.ts

@@ -303,17 +303,17 @@ export function stainlessDocs(config: StainlessDocsUserConfig): AstroIntegration
     stainlessDocsIntegration(normalizedConfig, apiReferenceBasePath),
     conditionalIntegration({
       condition: !config.experimental?.disableProseMarkdownRendering,
-      integration: stainlessDocsMarkdownRenderer(),
+      integration: stainlessDocsMarkdownRenderer({ apiReferenceBasePath }),
       reason: 'disabled by experimental config "disableProseMarkdownRendering"',
     }),
     conditionalIntegration({
       condition: !config.experimental?.disableStainlessProseIndexing,
-      integration: stainlessDocsAlgoliaProseIndexing(),
+      integration: stainlessDocsAlgoliaProseIndexing({ apiReferenceBasePath }),
       reason: 'disabled by experimental config "disableStainlessProseIndexing"',
     }),
     conditionalIntegration({
       condition: !config.experimental?.disableStainlessProseIndexing,
-      integration: stainlessDocsVectorProseIndexing(normalizedConfig),
+      integration: stainlessDocsVectorProseIndexing(normalizedConfig, apiReferenceBasePath),
       reason: 'disabled by experimental config "disableStainlessProseIndexing"',
     }),
   ];

package/stl-docs/proseDocSync.ts

@@ -304,7 +304,10 @@ async function syncProseDocuments(opts: {
 
 // ─── Astro integration ──────────────────────────────────────────────
 
-export function stainlessDocsVectorProseIndexing(config: NormalizedStainlessDocsConfig): AstroIntegration {
+export function stainlessDocsVectorProseIndexing(
+  config: NormalizedStainlessDocsConfig,
+  apiReferenceBasePath: string | null,
+): AstroIntegration {
   return {
     name: 'stl-docs-prose-indexing',
     hooks: {
@@ -328,7 +331,7 @@ export function stainlessDocsVectorProseIndexing(config: NormalizedStainlessDocs
           return;
         }
 
-        const pages = await getProsePages({ outputBasePath });
+        const pages = await getProsePages({ apiReferenceBasePath, outputBasePath });
         if (pages.length === 0) {
           logger.info('No prose pages found to index for vector search');
           return;

package/stl-docs/proseMarkdown/proseMarkdownIntegration.ts

@@ -6,7 +6,11 @@ import { getSharedLogger } from '../../shared/getSharedLogger';
 import { bold } from '../../shared/terminalUtils';
 import { getProsePages } from '../../shared/getProsePages';
 
-export function stainlessDocsMarkdownRenderer(): AstroIntegration {
+export function stainlessDocsMarkdownRenderer({
+  apiReferenceBasePath,
+}: {
+  apiReferenceBasePath: string | null;
+}): AstroIntegration {
   return {
     name: 'stl-docs-md',
     hooks: {
@@ -19,7 +23,7 @@ export function stainlessDocsMarkdownRenderer(): AstroIntegration {
       'astro:build:done': async ({ logger: localLogger, dir }) => {
         const logger = getSharedLogger({ fallback: localLogger });
         const outputBasePath = dir.pathname;
-        const pagesToRender = await getProsePages({ outputBasePath });
+        const pagesToRender = await getProsePages({ apiReferenceBasePath, outputBasePath });
 
         logger.info(bold(`Building ${pagesToRender.length} Markdown pages for prose content`));
 

package/stl-docs/proseSearchIndexing.ts

@@ -174,7 +174,11 @@ export function* indexHTML(
   }
 }
 
-export function stainlessDocsAlgoliaProseIndexing(): AstroIntegration {
+export function stainlessDocsAlgoliaProseIndexing({
+  apiReferenceBasePath,
+}: {
+  apiReferenceBasePath: string | null;
+}): AstroIntegration {
   return {
     name: 'stl-docs-prose-indexing',
     hooks: {
@@ -193,7 +197,7 @@ export function stainlessDocsAlgoliaProseIndexing(): AstroIntegration {
           return;
         }
 
-        const pagesToRender = await getProsePages({ outputBasePath });
+        const pagesToRender = await getProsePages({ apiReferenceBasePath, outputBasePath });
         logger.info(bold(`Indexing ${pagesToRender.length} prose pages for algolia search`));
 
         const objects = [];

package/shared/getProsePages.test.ts

@@ -1,130 +0,0 @@
-import type { Dirent } from 'fs';
-import { describe, expect, it, vi, beforeEach } from 'vitest';
-import { join } from 'path';
-
-vi.mock('fs/promises', () => ({
-  readdir: vi.fn(),
-  readFile: vi.fn(),
-}));
-
-import { readdir, readFile } from 'fs/promises';
-import { getProsePages } from './getProsePages';
-
-const mockedReaddir = vi.mocked(readdir);
-const mockedReadFile = vi.mocked(readFile);
-
-function fakeDirent(parentPath: string, name: string, isFile = true): Dirent {
-  return {
-    name,
-    parentPath,
-    path: parentPath,
-    isFile: () => isFile,
-    isDirectory: () => !isFile,
-    isBlockDevice: () => false,
-    isCharacterDevice: () => false,
-    isFIFO: () => false,
-    isSocket: () => false,
-    isSymbolicLink: () => false,
-  } as Dirent;
-}
-
-function stubManifest(apiReferencePages: string[]) {
-  mockedReadFile.mockResolvedValue(JSON.stringify({ astroBase: '/', apiReferencePages }));
-}
-
-function stubReaddir(dirents: Dirent[]) {
-  // readdir has many overloads; cast to match the withFileTypes variant
-  mockedReaddir.mockResolvedValue(dirents as unknown as Awaited<ReturnType<typeof readdir>>);
-}
-
-describe('getProsePages', () => {
-  beforeEach(() => {
-    vi.resetAllMocks();
-    // Default: no manifest
-    mockedReadFile.mockRejectedValue(new Error('ENOENT'));
-  });
-
-  it('does not return API reference pages as prose when basePath is ""', async () => {
-    stubManifest(['resources/users/index.html', 'resources/users/methods/create/index.html']);
-    stubReaddir([
-      fakeDirent('/out/guides', 'intro.html'),
-      fakeDirent('/out/resources/users', 'index.html'),
-      fakeDirent('/out/resources/users/methods/create', 'index.html'),
-    ]);
-
-    const result = await getProsePages({ outputBasePath: '/out' });
-
-    // resources/users/** are API reference pages, not prose
-    expect(result).not.toContainEqual(join('/out/resources/users', 'index.html'));
-    expect(result).not.toContainEqual(join('/out/resources/users/methods/create', 'index.html'));
-    expect(result).toContainEqual(join('/out/guides', 'intro.html'));
-  });
-
-  it('returns all HTML files when no manifest exists', async () => {
-    stubReaddir([fakeDirent('/out', 'index.html'), fakeDirent('/out/guides', 'intro.html')]);
-
-    const result = await getProsePages({ outputBasePath: '/out' });
-
-    expect(result).toEqual([join('/out', 'index.html'), join('/out/guides', 'intro.html')]);
-  });
-
-  it('returns all HTML files when manifest has empty apiReferencePages', async () => {
-    stubManifest([]);
-    stubReaddir([fakeDirent('/out', 'index.html'), fakeDirent('/out/guides', 'intro.html')]);
-
-    const result = await getProsePages({ outputBasePath: '/out' });
-
-    expect(result).toEqual([join('/out', 'index.html'), join('/out/guides', 'intro.html')]);
-  });
-
-  it('excludes files listed in the manifest', async () => {
-    stubManifest(['api/resources/users/index.html', 'api/resources/users/methods/create/index.html']);
-    stubReaddir([
-      fakeDirent('/out', 'index.html'),
-      fakeDirent('/out/guides', 'intro.html'),
-      fakeDirent('/out/api/resources/users', 'index.html'),
-      fakeDirent('/out/api/resources/users/methods/create', 'index.html'),
-    ]);
-
-    const result = await getProsePages({ outputBasePath: '/out' });
-
-    expect(result).toEqual([join('/out', 'index.html'), join('/out/guides', 'intro.html')]);
-  });
-
-  it('excludes non-HTML files', async () => {
-    stubReaddir([
-      fakeDirent('/out', 'index.html'),
-      fakeDirent('/out', 'style.css'),
-      fakeDirent('/out', 'app.js'),
-    ]);
-
-    const result = await getProsePages({ outputBasePath: '/out' });
-
-    expect(result).toEqual([join('/out', 'index.html')]);
-  });
-
-  it('excludes directories', async () => {
-    stubReaddir([fakeDirent('/out', 'index.html'), fakeDirent('/out', 'guides', false)]);
-
-    const result = await getProsePages({ outputBasePath: '/out' });
-
-    expect(result).toEqual([join('/out', 'index.html')]);
-  });
-
-  it('returns empty when all HTML files are in the manifest', async () => {
-    stubManifest(['index.html', 'resources/users/index.html']);
-    stubReaddir([fakeDirent('/out', 'index.html'), fakeDirent('/out/resources/users', 'index.html')]);
-
-    const result = await getProsePages({ outputBasePath: '/out' });
-
-    expect(result).toEqual([]);
-  });
-
-  it('returns empty when output has no HTML files', async () => {
-    stubReaddir([fakeDirent('/out', 'style.css')]);
-
-    const result = await getProsePages({ outputBasePath: '/out' });
-
-    expect(result).toEqual([]);
-  });
-});