@umami/shiso 1.11.0 → 1.13.0

package/scripts/load-docs-config.mjs

@@ -1,5 +1,14 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { expandNavigationGlobs, hasNavigationGlobs } from './expand-navigation-globs.mjs';
+import { expandOpenApiNavigation, hasOpenApiItems } from './expand-openapi-navigation.mjs';
+import {
+  generateOpenApiStubs,
+  loadOpenApiSpec,
+  normalizeOperations,
+  resolveApiDirectory,
+} from './lib/openapi.mjs';
+import { loadShisoConfig } from './load-shiso-config.mjs';
 
 /** Error raised while locating, reading, or parsing a Shiso configuration file. */
 export class DocsConfigLoadError extends Error {
@@ -220,16 +229,53 @@ async function resolveConfigReferences(entryPath, projectRoot) {
  * stable place from which to resolve relative references without changing
  * every build-time consumer again.
  */
-export async function loadDocsConfig({ root = process.cwd(), configFile = 'docs.json' } = {}) {
+export async function loadDocsConfig({
+  root = process.cwd(),
+  configFile = 'docs.json',
+  expandGlobs = true,
+} = {}) {
   const requestedRoot = path.resolve(root);
   const requestedSourcePath = path.resolve(requestedRoot, configFile);
-  const { config, projectRoot, sourcePaths } = await resolveConfigReferences(
-    requestedSourcePath,
-    requestedRoot,
-  );
+  const {
+    config: sourceConfig,
+    projectRoot,
+    sourcePaths,
+  } = await resolveConfigReferences(requestedSourcePath, requestedRoot);
   const sourcePath = sourcePaths[0] || requestedSourcePath;
+  const hasGlobs = hasNavigationGlobs(sourceConfig.navigation);
+  let working = sourceConfig;
+  let specPath;
+
+  // OpenAPI expansion runs before glob expansion so generated stub pages are
+  // visible to navigation globs and every downstream consumer.
+  if (expandGlobs && working.api?.spec) {
+    const loadedSpec = await loadOpenApiSpec({ root: projectRoot, specPath: working.api.spec });
+    specPath = loadedSpec.specPath;
+    const operations = normalizeOperations(loadedSpec.spec);
+    const directory = resolveApiDirectory(working.api);
+    const { config: shisoConfig } = await loadShisoConfig({ root: projectRoot });
+
+    await generateOpenApiStubs({
+      root: projectRoot,
+      contentDir: shisoConfig.contentDir,
+      directory,
+      operations,
+    });
+    working = expandOpenApiNavigation(working, { operations, directory });
+  } else if (expandGlobs && hasOpenApiItems(working.navigation)) {
+    throw new Error(
+      'Navigation contains an { "openapi" } entry but docs.json has no "api.spec" setting.',
+    );
+  }
+
+  const config = expandGlobs
+    ? await expandNavigationGlobs(working, {
+        root: projectRoot,
+        contentDir: (await loadShisoConfig({ root: projectRoot })).config.contentDir,
+      })
+    : working;
 
-  return { config, projectRoot, sourcePath, sourcePaths };
+  return { config, projectRoot, sourcePath, sourcePaths, hasGlobs, specPath };
 }
 
 export async function loadDocsSchema({

package/scripts/load-shiso-config.mjs

@@ -15,7 +15,9 @@ import { createJiti } from 'jiti';
 /** Candidate filenames in precedence order. Exactly one may exist. */
 export const SHISO_CONFIG_FILES = ['shiso.config.ts', 'shiso.config.mjs', 'shiso.config.js'];
 
-const KNOWN_KEYS = ['docsPrefix', 'contentDir', 'siteUrl', 'locale'];
+const STRING_KEYS = ['docsPrefix', 'contentDir', 'siteUrl', 'locale'];
+const KNOWN_KEYS = [...STRING_KEYS, 'mdx'];
+const MDX_KEYS = ['remarkPlugins', 'rehypePlugins'];
 
 let importGeneration = 0;
 
@@ -53,12 +55,45 @@ function assertStringOption(raw, key, sourcePath) {
   }
 }
 
+function resolveMdxConfig(value, sourcePath) {
+  if (value === undefined) return undefined;
+
+  if (!isPlainObject(value)) {
+    throw new ShisoConfigLoadError('Shiso config option "mdx" must be a plain object.', {
+      code: 'INVALID_OPTION',
+      sourcePath,
+    });
+  }
+
+  const unknownKeys = Object.keys(value).filter(key => !MDX_KEYS.includes(key));
+  if (unknownKeys.length) {
+    throw new ShisoConfigLoadError(
+      `Shiso config option "mdx" has unknown ${unknownKeys.length === 1 ? 'key' : 'keys'} ${unknownKeys.map(key => `"${key}"`).join(', ')}. Supported keys: ${MDX_KEYS.join(', ')}.`,
+      { code: 'UNKNOWN_OPTION', sourcePath },
+    );
+  }
+
+  for (const key of MDX_KEYS) {
+    if (value[key] !== undefined && !Array.isArray(value[key])) {
+      throw new ShisoConfigLoadError(`Shiso config option "mdx.${key}" must be an array.`, {
+        code: 'INVALID_OPTION',
+        sourcePath,
+      });
+    }
+  }
+
+  return {
+    remarkPlugins: value.remarkPlugins || [],
+    rehypePlugins: value.rehypePlugins || [],
+  };
+}
+
 /**
  * Applies defaults and normalization. Single source of truth for resolved
  * values, so runtime and build-time consumers never re-implement defaulting.
  */
 export function resolveShisoConfig(raw = {}, sourcePath = null) {
-  for (const key of KNOWN_KEYS) {
+  for (const key of STRING_KEYS) {
     assertStringOption(raw, key, sourcePath);
   }
 
@@ -67,6 +102,7 @@ export function resolveShisoConfig(raw = {}, sourcePath = null) {
     contentDir: (raw.contentDir ?? 'content/docs').trim().replace(/^\/+|\/+$/g, ''),
     siteUrl: raw.siteUrl?.trim().replace(/\/+$/, '') || undefined,
     locale: raw.locale?.trim() || 'en-US',
+    mdx: resolveMdxConfig(raw.mdx, sourcePath),
   };
 }
 
@@ -108,7 +144,13 @@ export async function loadShisoConfig({ root = process.cwd() } = {}) {
   }
 
   if (found.length === 0) {
-    return { config: resolveShisoConfig(), raw: {}, projectRoot, sourcePath: null, sourcePaths: [] };
+    return {
+      config: resolveShisoConfig(),
+      raw: {},
+      projectRoot,
+      sourcePath: null,
+      sourcePaths: [],
+    };
   }
 
   const sourcePath = found[0];

package/scripts/prerender.mjs

@@ -16,6 +16,13 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import process from 'node:process';
 import { pathToFileURL } from 'node:url';
+import {
+  loadOpenApiSpec,
+  normalizeOperationKey,
+  normalizeOperations,
+  operationToMarkdown,
+} from './lib/openapi.mjs';
+import { loadDocsConfig } from './load-docs-config.mjs';
 
 const DEFAULT_HEAD_OPEN = '<!--shiso-default-head-->';
 const DEFAULT_HEAD_CLOSE = '<!--/shiso-default-head-->';
@@ -31,8 +38,17 @@ if (!template.includes('<!--app-html-->')) {
   );
 }
 
-const { render, getRoutes, getRedirects, getSitemapEntries, getMarkdownPages, docsHomeUrl } =
-  await import(pathToFileURL(path.join(root, 'dist', 'server', 'entry-server.js')).href);
+const {
+  render,
+  getRoutes,
+  getRedirects,
+  getSitemapEntries,
+  getMarkdownPages,
+  getLlmsPages,
+  docsHomeUrl,
+  siteName,
+  siteDescription,
+} = await import(pathToFileURL(path.join(root, 'dist', 'server', 'entry-server.js')).href);
 
 /** Vite's `base`, normalized to "" or "/prefix". */
 function readBase() {
@@ -104,6 +120,25 @@ if (docsHomeUrl && docsHomeUrl !== '/' && !routes.includes('/')) {
   );
 }
 
+// Pages bound to an API operation publish the generated reference as markdown
+// too, so the .md copies and llms-full.txt stay useful to AI tools.
+let openApiByKey;
+{
+  const docsConfig = (await loadDocsConfig({ root, expandGlobs: false })).config;
+  if (docsConfig.api?.spec) {
+    const { spec } = await loadOpenApiSpec({ root, specPath: docsConfig.api.spec });
+    openApiByKey = new Map(normalizeOperations(spec).map(operation => [operation.key, operation]));
+  }
+}
+
+function withOperationMarkdown(source) {
+  if (!openApiByKey) return source;
+  const frontmatter = source.match(/^---\s*\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1] || '';
+  const key = normalizeOperationKey(frontmatter.match(/^openapi:\s*(.+)$/m)?.[1]);
+  const operation = key ? openApiByKey.get(key) : undefined;
+  return operation ? `${source.trimEnd()}\n\n${operationToMarkdown(operation)}\n` : source;
+}
+
 // Raw markdown next to every page: "/docs/installation" -> "docs/installation.md".
 // Served for the contextual menu's copy/view options and for AI tools.
 const markdownPages = getMarkdownPages();
@@ -111,9 +146,52 @@ const markdownPages = getMarkdownPages();
 for (const { route, filePath } of markdownPages) {
   const source = await readFile(path.join(root, ...filePath.split('/').filter(Boolean)), 'utf8');
   const relative = withBase(route).replace(/^\//, '') || 'index';
-  await writePage(path.join(clientDir, `${relative}.md`), source);
+  await writePage(path.join(clientDir, `${relative}.md`), withOperationMarkdown(source));
+}
+
+// AI discovery files. llms.txt is the concise, ordered map; llms-full.txt is
+// the same public corpus concatenated for tools that prefer one fetch.
+const llmsPages = getLlmsPages();
+
+function markdownHref(route) {
+  const relative = withBase(route).replace(/^\//, '') || 'index';
+  return `/${relative}.md`;
+}
+
+const llmsHeader = [
+  `# ${siteName || 'Documentation'}`,
+  siteDescription ? `> ${siteDescription}` : null,
+]
+  .filter(Boolean)
+  .join('\n\n');
+const llmsLinks = llmsPages
+  .map(
+    page =>
+      `- [${page.title}](${markdownHref(page.route)})${page.description ? `: ${page.description}` : ''}`,
+  )
+  .join('\n');
+
+await writePage(
+  path.join(clientDir, 'llms.txt'),
+  `${llmsHeader}\n\n## Documentation\n\n${llmsLinks}\n`,
+);
+
+const llmsFullSections = [];
+for (const page of llmsPages) {
+  const source = await readFile(
+    path.join(root, ...page.filePath.split('/').filter(Boolean)),
+    'utf8',
+  );
+  llmsFullSections.push(
+    [`# ${page.title}`, `Source: ${markdownHref(page.route)}`, source.trim()].join('\n\n'),
+  );
 }
 
+await writePage(
+  path.join(clientDir, 'llms-full.txt'),
+  `${llmsHeader}\n\n${llmsFullSections.join('\n\n---\n\n')}\n`,
+);
+
 // Redirect pages. Static hosting cannot serve real 301s, so each redirect
 // gets the same canonical + meta refresh + immediate replace treatment as
 // the root entry. Real pages always win over redirect rules.
@@ -187,6 +265,8 @@ if (stray.length) {
 const extras = [
   redirects.length ? `${redirects.length} redirects` : null,
   sitemapEntries.length ? 'sitemap.xml' : null,
+  'llms.txt',
+  'llms-full.txt',
 ]
   .filter(Boolean)
   .join(', ');

package/scripts/vite-docs-config.mjs

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { loadDocsConfig } from './load-docs-config.mjs';
-import { SHISO_CONFIG_FILES, loadShisoConfig } from './load-shiso-config.mjs';
+import { loadShisoConfig, SHISO_CONFIG_FILES } from './load-shiso-config.mjs';
 
 export const VIRTUAL_DOCS_CONFIG_ID = 'virtual:shiso-docs-config';
 export const VIRTUAL_SHISO_CONFIG_ID = 'virtual:shiso-config';
@@ -11,6 +11,13 @@ function renderConfigModule(config) {
   return `export default ${JSON.stringify(config)};`;
 }
 
+function renderShisoConfigModule(config) {
+  // Compiler plugins are functions used by vite.config.ts and cannot be
+  // serialized into the virtual module consumed by the browser runtime.
+  const { mdx: _mdx, ...runtimeConfig } = config;
+  return renderConfigModule(runtimeConfig);
+}
+
 /**
  * Creates the single config state shared by a Vite build and application
  * modules. Two virtual modules keep Node-only file loading out of the browser
@@ -35,6 +42,7 @@ export async function createDocsConfigModule({
   return {
     getConfig: () => loaded.config,
     getShisoConfig: () => loadedShiso.config,
+    getSpecPath: () => loaded.specPath,
     getSourcePaths: () => [...loaded.sourcePaths, ...loadedShiso.sourcePaths],
     sourcePath: loaded.sourcePath,
     shisoSourcePath: loadedShiso.sourcePath,
@@ -64,26 +72,39 @@ export async function createDocsConfigModule({
           for (const sourcePath of loadedShiso.sourcePaths) {
             this.addWatchFile(sourcePath);
           }
-          return renderConfigModule(loadedShiso.config);
+          return renderShisoConfigModule(loadedShiso.config);
         }
 
         return undefined;
       },
       async handleHotUpdate(context) {
         const changedPath = path.resolve(context.file);
-        const isDocsSource = loaded.sourcePaths.includes(changedPath);
+        const isDocsSource =
+          loaded.sourcePaths.includes(changedPath) || changedPath === loaded.specPath;
         const isShisoSource = shisoCandidatePaths.includes(changedPath);
+        const contentRoot = path.resolve(root, loadedShiso.config.contentDir);
+        const relativeContentPath = path.relative(contentRoot, changedPath);
+        const isGlobContent =
+          loaded.hasGlobs &&
+          /\.(?:md|mdx)$/.test(changedPath) &&
+          relativeContentPath !== '..' &&
+          !relativeContentPath.startsWith(`..${path.sep}`) &&
+          !path.isAbsolute(relativeContentPath);
 
-        if (!isDocsSource && !isShisoSource) {
+        if (!isDocsSource && !isShisoSource && !isGlobContent) {
           return;
         }
 
-        const resolvedId = isDocsSource ? RESOLVED_DOCS_CONFIG_ID : RESOLVED_SHISO_CONFIG_ID;
+        const resolvedId =
+          isDocsSource || isGlobContent ? RESOLVED_DOCS_CONFIG_ID : RESOLVED_SHISO_CONFIG_ID;
 
-        if (isDocsSource) {
+        if (isDocsSource || isGlobContent) {
           loaded = await loadDocsConfig(options);
         } else {
           loadedShiso = await loadShisoConfig({ root });
+          // contentDir may have changed, so glob expansion must use the new
+          // location before the full reload.
+          loaded = await loadDocsConfig(options);
         }
 
         const configModule = context.server.moduleGraph.getModuleById(resolvedId);

package/src/App.tsx

@@ -1,6 +1,5 @@
 import '@fontsource-variable/inter/index.css';
 import '@fontsource/jetbrains-mono/400.css';
-import 'highlight.js/styles/github.css';
 import '@umami/shiso/styles.css';
 
 import { MDXProvider } from '@mdx-js/react';

package/src/components/CodeBlock.tsx

@@ -1,20 +1,97 @@
-import { type ReactNode, useRef, useState } from 'react';
+import type { ReactNode } from 'react';
+import { type ComponentProps, type CSSProperties, useRef, useState } from 'react';
 import { CheckIcon, Copy } from '@/components/icons';
 import { Button } from '@/components/ui/button';
 import { ScrollArea } from '@/components/ui/scroll-area';
+import { cn } from '@/lib/utils';
+import { Mermaid, type MermaidPlacement } from './docs/Mermaid';
 
-export interface CodeBlockProps {
-  children?: ReactNode;
-  className?: string;
+/**
+ * Renders a fenced code block. The `data-*` props are produced at build time by
+ * `lib/rehype-shiki.ts`; see that file for the markup contract.
+ */
+export interface CodeBlockProps extends ComponentProps<'pre'> {
+  'data-title'?: string;
+  'data-language'?: string;
+  'data-line-numbers'?: string;
+  'data-line-start'?: string;
+  'data-line-count'?: string;
+  'data-diff-markers'?: string;
+  'data-placement'?: MermaidPlacement;
+  'data-actions'?: string;
 }
 
-export function CodeBlock({ children, className }: CodeBlockProps) {
+function reactChildrenToText(node: ReactNode): string {
+  if (typeof node === 'string' || typeof node === 'number') {
+    return String(node);
+  }
+  if (Array.isArray(node)) {
+    return node.map(reactChildrenToText).join('');
+  }
+  if (node && typeof node === 'object' && 'props' in (node as object)) {
+    const props = (node as { props?: { children?: ReactNode; value?: unknown } }).props;
+    if (typeof props?.value === 'string') {
+      return props.value;
+    }
+    return reactChildrenToText(props?.children);
+  }
+  return '';
+}
+
+/**
+ * Joins the text of each rendered line. Lines marked as removed by
+ * `// [!code --]` are skipped so the clipboard holds the "after" state; in a
+ * `diff` block the +/- lines are content and are copied verbatim.
+ */
+function copyText(pre: HTMLPreElement | null, language?: string): string {
+  if (!pre) {
+    return '';
+  }
+
+  const lines = [...pre.querySelectorAll<HTMLElement>('.line')];
+  if (!lines.length) {
+    return pre.textContent || '';
+  }
+
+  return lines
+    .filter(line => language === 'diff' || line.dataset.diff !== 'remove')
+    .map(line => line.textContent || '')
+    .join('\n');
+}
+
+export function CodeBlock({ children, className, style, ...rest }: CodeBlockProps) {
+  const {
+    'data-title': title,
+    'data-language': language,
+    'data-line-start': lineStart,
+    'data-line-count': lineCount,
+    'data-placement': placement,
+    'data-actions': actions,
+    ...preProps
+  } = rest;
   const textInput = useRef<HTMLPreElement>(null);
   const [copied, setCopied] = useState(false);
 
+  // ```mermaid fences render as diagrams; the raw definition stays in the
+  // markup for search indexing and no-JS fallbacks.
+  if (language === 'mermaid') {
+    return (
+      <Mermaid
+        chart={reactChildrenToText(children).replace(/\n$/, '')}
+        title={title}
+        placement={placement}
+        actions={actions === undefined ? undefined : actions !== 'false'}
+      />
+    );
+  }
+
+  const start = Number(lineStart) || 1;
+  const lastLine = start + Math.max(Number(lineCount) || 1, 1) - 1;
+  const gutter = `${String(lastLine).length}ch`;
+
   const handleCopy = () => {
     setCopied(true);
-    navigator?.clipboard?.writeText(textInput.current?.textContent || '');
+    navigator?.clipboard?.writeText(copyText(textInput.current, language));
 
     setTimeout(() => {
       setCopied(false);
@@ -23,10 +100,30 @@ export function CodeBlock({ children, className }: CodeBlockProps) {
 
   return (
     <div data-slot="code-block" className="relative my-5 overflow-hidden rounded-lg bg-card">
+      {title ? (
+        <div
+          data-slot="code-block-header"
+          className="flex h-9 items-center border-border border-b px-3 pr-12 font-mono text-muted-foreground text-xs"
+        >
+          {title}
+        </div>
+      ) : null}
       <ScrollArea scrollbars="horizontal" className="w-full">
         <pre
           ref={textInput}
-          className={`code-block p-3 pr-12 text-sm text-foreground leading-[1.6] font-mono ${className || ''}`}
+          {...preProps}
+          data-language={language}
+          style={
+            {
+              ...style,
+              counterReset: `line ${start - 1}`,
+              '--code-gutter': gutter,
+            } as CSSProperties
+          }
+          className={cn(
+            'code-block w-max min-w-full py-3 font-mono text-foreground text-sm leading-[1.6]',
+            className,
+          )}
         >
           {children}
         </pre>
@@ -35,7 +132,10 @@ export function CodeBlock({ children, className }: CodeBlockProps) {
         type="button"
         variant="ghost"
         size="icon-sm"
-        className="absolute top-2.5 right-3 inline-flex size-7 items-center justify-center rounded-sm text-muted-foreground hover:bg-accent hover:text-accent-foreground"
+        className={cn(
+          'absolute right-3 inline-flex size-7 items-center justify-center rounded-sm text-muted-foreground hover:bg-accent hover:text-accent-foreground',
+          title ? 'top-1' : 'top-2.5',
+        )}
         onClick={handleCopy}
         aria-label="Copy code"
       >

package/src/components/DocContent.tsx

@@ -1,9 +1,12 @@
 import { Link } from 'react-router';
 import { ContextualMenu } from '@/components/ContextualMenu';
+import { Badge } from '@/components/docs/Badge';
 import { ArrowLeft, ArrowRight, FileText } from '@/components/icons';
+import { OpenApiOperation } from '@/components/OpenApiOperation';
 import { getLastModified } from '@/lib/content';
 import { getScopeForPage } from '@/lib/docs-config';
 import { resolveLocale } from '@/lib/locale';
+import { getOperation, methodColor } from '@/lib/openapi';
 import { docsSite, getPageByPathname } from '@/lib/site-config';
 import { resolveContextualOptions } from '@/lib/site-model';
 import type { DocModule, NormalizedDocsPage, RelatedEntry, SiteModel } from '@/lib/types';
@@ -81,6 +84,7 @@ export function DocContent({ page, doc, site }: DocContentProps) {
       : page.section;
   const contextualOptions = resolveContextualOptions(site.contextualOptions, page, site.labels);
   const related = resolveRelated(doc.frontmatter?.related);
+  const operation = getOperation(doc.frontmatter?.openapi);
   // Dates follow the page's language when it is a valid locale code.
   const dateFormat = new Intl.DateTimeFormat(resolveLocale(page.language, site.locale), {
     dateStyle: 'medium',
@@ -111,12 +115,26 @@ export function DocContent({ page, doc, site }: DocContentProps) {
         )}
         <ContextualMenu options={contextualOptions} labels={site.labels} />
       </div>
+      {operation && (
+        <div className="mt-3 flex flex-wrap items-center gap-2">
+          <Badge color={methodColor(operation.method)} size="sm" className="font-mono">
+            {operation.method}
+          </Badge>
+          <code className="font-mono text-muted-foreground text-sm">{operation.path}</code>
+          {operation.deprecated && (
+            <Badge color="red" size="sm" stroke>
+              deprecated
+            </Badge>
+          )}
+        </div>
+      )}
       {description && (
         <p className="mt-3 mb-8 text-lg text-muted-foreground leading-relaxed">{description}</p>
       )}
       <div className="docs-markdown">
         <Content />
       </div>
+      {operation && <OpenApiOperation operation={operation} />}
       {lastModified && (
         <div className="mt-8 text-sm text-muted-foreground">
           {site.labels.lastUpdated}{' '}

package/src/components/Docs.tsx

@@ -1,6 +1,7 @@
 import { useEffect, useState } from 'react';
 import { useLocation, useNavigate } from 'react-router';
 import { DocContent } from '@/components/DocContent';
+import { PanelProvider, usePanelContent } from '@/components/docs/panel-context';
 import { Footer } from '@/components/Footer';
 import { Menu } from '@/components/icons';
 import { LanguageSwitcher } from '@/components/LanguageSwitcher';
@@ -11,8 +12,9 @@ import { Button } from '@/components/ui/button';
 import { Sheet, SheetContent, SheetTitle, SheetTrigger } from '@/components/ui/sheet';
 import { VersionSwitcher } from '@/components/VersionSwitcher';
 import { renderInlineMarkdown } from '@/lib/inline-markdown';
+import { getOperation, operationSections } from '@/lib/openapi';
 import { docsHomeUrl, getScopeByPathname } from '@/lib/site-config';
-import type { DocModule, NormalizedDocsPage, SiteModel } from '@/lib/types';
+import type { DocModule, NormalizedDocsPage, SiteModel, TocEntry } from '@/lib/types';
 
 /**
  * 404 view driven by the `errors.404` config key. The standard defaults to
@@ -45,11 +47,46 @@ export interface DocsProps {
 }
 
 export function Docs({ page, doc, site }: DocsProps) {
+  if (!page || !doc) {
+    return (
+      <div className="flex min-h-full flex-col">
+        <div className="grow">
+          <NotFound site={site} />
+        </div>
+        <Footer footer={site.footer} />
+      </div>
+    );
+  }
+
+  // API reference pages append their generated section anchors to the TOC.
+  const operation = getOperation(doc.frontmatter?.openapi);
+  const toc = operation ? [...(doc.toc || []), ...operationSections(operation)] : doc.toc;
+
+  return (
+    <PanelProvider>
+      <DocsBody page={page} doc={doc} site={site} toc={toc} />
+    </PanelProvider>
+  );
+}
+
+function DocsBody({
+  page,
+  doc,
+  site,
+  toc,
+}: {
+  page: NormalizedDocsPage;
+  doc: DocModule;
+  site: SiteModel;
+  toc: TocEntry[] | undefined;
+}) {
   const { pathname } = useLocation();
   const [menuOpen, setMenuOpen] = useState(false);
   // Navigation follows the scope (version/language) that owns the current page.
   const scopeDocs = getScopeByPathname(pathname).docs;
   const { tabs, navigation } = scopeDocs;
+  // A <Panel> in the page replaces the table of contents in the right rail.
+  const panel = usePanelContent();
 
   // Close the mobile menu and start each newly loaded page at the top. Hash
   // links keep their native section-scrolling behavior.
@@ -61,17 +98,6 @@ export function Docs({ page, doc, site }: DocsProps) {
     }
   }, [pathname]);
 
-  if (!page || !doc) {
-    return (
-      <div className="flex min-h-full flex-col">
-        <div className="grow">
-          <NotFound site={site} />
-        </div>
-        <Footer footer={site.footer} />
-      </div>
-    );
-  }
-
   return (
     <div className="flex min-h-full flex-col gap-6 lg:gap-0">
       <Sheet open={menuOpen} onOpenChange={setMenuOpen}>
@@ -123,11 +149,13 @@ export function Docs({ page, doc, site }: DocsProps) {
           <div className="flex grow items-start gap-12">
             <DocContent page={page} doc={doc} site={site} />
             <div className="hidden min-w-0 max-w-60 basis-60 self-start lg:sticky lg:top-[calc(var(--header-height)+1.5rem)] lg:block lg:shrink-0">
-              <PageLinks
-                items={doc.toc}
-                title={site.labels.tableOfContents}
-                navigationLabel={site.labels.tableOfContentsNavigation}
-              />
+              {panel ?? (
+                <PageLinks
+                  items={toc}
+                  title={site.labels.tableOfContents}
+                  navigationLabel={site.labels.tableOfContentsNavigation}
+                />
+              )}
             </div>
           </div>
           <Footer footer={site.footer} className="lg:mr-72" />