@umami/shiso 1.11.0 → 1.12.0

package/src/components/OpenApiOperation.tsx

@@ -0,0 +1,197 @@
+import { CodeBlock } from '@/components/CodeBlock';
+import { Badge } from '@/components/docs/Badge';
+import { CodeGroup } from '@/components/docs/CodeGroup';
+import { Expandable } from '@/components/docs/Expandable';
+import { ParamField } from '@/components/docs/ParamField';
+import { ResponseField } from '@/components/docs/ResponseField';
+import { operationSections, statusColor } from '@/lib/openapi';
+import type { NormalizedOperation, SchemaNode } from '@/lib/types';
+
+type ParamLocation = 'path' | 'query' | 'header' | 'cookie';
+
+const PARAM_LOCATIONS: ParamLocation[] = ['path', 'query', 'header', 'cookie'];
+
+function FieldChildren({ node }: { node: SchemaNode }) {
+  return (
+    <>
+      {node.description}
+      {node.enum && node.enum.length > 0 && (
+        <div className="mt-1">
+          Options:{' '}
+          {node.enum.map((value, index) => (
+            <span key={value}>
+              {index > 0 && ', '}
+              <code>{value}</code>
+            </span>
+          ))}
+        </div>
+      )}
+      {node.children && node.children.length > 0 && (
+        <Expandable title="properties">
+          {node.children.map(child => (
+            <SchemaField key={child.name || child.type} node={child} />
+          ))}
+        </Expandable>
+      )}
+    </>
+  );
+}
+
+function SchemaField({ node }: { node: SchemaNode }) {
+  return (
+    <ResponseField
+      name={node.name || node.type}
+      type={node.name ? node.type : undefined}
+      required={node.required}
+      deprecated={node.deprecated}
+      default={node.default}
+    >
+      <FieldChildren node={node} />
+    </ResponseField>
+  );
+}
+
+/** Renders a schema tree: a root object's properties, or the node itself. */
+function SchemaFields({ node }: { node: SchemaNode }) {
+  if (!node.name && node.children?.length) {
+    return (
+      <>
+        {node.children.map(child => (
+          <SchemaField key={child.name || child.type} node={child} />
+        ))}
+      </>
+    );
+  }
+
+  return <SchemaField node={node} />;
+}
+
+function HighlightedCode({
+  language,
+  title,
+  html,
+  source,
+  lineCount,
+}: {
+  language: string;
+  title?: string;
+  html?: string;
+  source: string;
+  lineCount?: number;
+}) {
+  return (
+    <CodeBlock
+      data-language={language}
+      data-title={title}
+      data-line-count={lineCount ? String(lineCount) : undefined}
+    >
+      {html ? (
+        // Highlighted at build time by the openapi generator; same markup as
+        // the rehype-shiki pipeline produces for fenced code blocks.
+        <code
+          className={`language-${language}`}
+          // biome-ignore lint/security/noDangerouslySetInnerHtml: build-time generated markup from the project's own OpenAPI spec.
+          dangerouslySetInnerHTML={{ __html: html }}
+        />
+      ) : (
+        <code className={`language-${language}`}>{source}</code>
+      )}
+    </CodeBlock>
+  );
+}
+
+export interface OpenApiOperationProps {
+  operation: NormalizedOperation;
+}
+
+/** The generated reference for one API operation, rendered under the page body. */
+export function OpenApiOperation({ operation }: OpenApiOperationProps) {
+  const sections = new Map(operationSections(operation).map(entry => [entry.name, entry.id]));
+  const showParameters = sections.has('Parameters');
+
+  return (
+    <div className="docs-markdown">
+      {showParameters && (
+        <section>
+          <h2 id={sections.get('Parameters')}>Parameters</h2>
+          {operation.security.length > 0 && (
+            <ParamField header="Authorization" type="string" required>
+              Authentication credentials, e.g. <code>Bearer &lt;token&gt;</code> (
+              {operation.security.join(', ')}).
+            </ParamField>
+          )}
+          {PARAM_LOCATIONS.map(location =>
+            operation.parameters[location].map(parameter => (
+              <ParamField
+                key={`${location}-${parameter.name}`}
+                {...{ [location]: parameter.name }}
+                type={parameter.type}
+                required={parameter.required}
+              >
+                <FieldChildren node={{ ...parameter, name: undefined, description: undefined }} />
+                {parameter.description}
+              </ParamField>
+            )),
+          )}
+        </section>
+      )}
+      {operation.requestBody && (
+        <section>
+          <h2 id={sections.get('Request body')}>Request body</h2>
+          <SchemaFields node={operation.requestBody.schema} />
+          {operation.requestBody.example && (
+            <HighlightedCode
+              language="json"
+              title="Example request"
+              html={operation.requestBody.exampleHtml}
+              source={operation.requestBody.example}
+            />
+          )}
+        </section>
+      )}
+      {operation.responses.length > 0 && (
+        <section>
+          <h2 id={sections.get('Responses')}>Responses</h2>
+          {operation.responses.map(response => (
+            <div key={response.status} className="mt-6 first:mt-0">
+              <div className="flex items-center gap-2">
+                <Badge color={statusColor(response.status)} size="sm">
+                  {response.status}
+                </Badge>
+                {response.description && (
+                  <span className="text-muted-foreground text-sm">{response.description}</span>
+                )}
+              </div>
+              {response.schema && <SchemaFields node={response.schema} />}
+              {response.example && (
+                <HighlightedCode
+                  language="json"
+                  title={`${response.status} example`}
+                  html={response.exampleHtml}
+                  source={response.example}
+                />
+              )}
+            </div>
+          ))}
+        </section>
+      )}
+      {operation.samples.length > 0 && (
+        <section>
+          <h2 id={sections.get('Code samples')}>Code samples</h2>
+          <CodeGroup>
+            {operation.samples.map(sample => (
+              <HighlightedCode
+                key={sample.language}
+                language={sample.language}
+                title={sample.label}
+                html={sample.html}
+                source={sample.source}
+                lineCount={sample.lineCount}
+              />
+            ))}
+          </CodeGroup>
+        </section>
+      )}
+    </div>
+  );
+}

package/src/components/SideNav.tsx

@@ -1,5 +1,6 @@
 import { type ReactNode, useEffect, useState } from 'react';
 import { Link, useLocation, useNavigate } from 'react-router';
+import { Badge as MethodBadge } from '@/components/docs/Badge';
 import { resolveIcon } from '@/components/docs/utils';
 import { ChevronRight, ExternalLink } from '@/components/icons';
 import { Badge } from '@/components/ui/badge';
@@ -7,6 +8,7 @@ import { Button } from '@/components/ui/button';
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@/components/ui/collapsible';
 import { ScrollArea } from '@/components/ui/scroll-area';
 import { flattenNav, isNodeHidden } from '@/lib/docs-config';
+import { methodColor } from '@/lib/openapi';
 import type { DocsTab, NavGroupNode, NavNode } from '@/lib/types';
 import { cn } from '@/lib/utils';
 
@@ -256,7 +258,7 @@ function NavNodes({
     }
 
     if (node.kind === 'page') {
-      const { url, label, icon, tag } = node.page;
+      const { url, label, icon, tag, method } = node.page;
       const isSelected = url === pathname;
 
       rendered.push(
@@ -274,7 +276,11 @@ function NavNodes({
         >
           {resolveIcon(icon)}
           {label}
-          {tag ? (
+          {method ? (
+            <MethodBadge color={methodColor(method)} size="xs" className="ml-auto font-mono">
+              {method === 'DELETE' ? 'DEL' : method}
+            </MethodBadge>
+          ) : tag ? (
             <Badge
               variant="secondary"
               className="ml-auto h-auto rounded-sm px-[0.35rem] py-[0.05rem] text-[0.7rem] text-muted-foreground uppercase"

package/src/components/docs/CodeGroup.tsx

@@ -39,14 +39,18 @@ export function CodeGroup({ children }: CodeGroupProps) {
   }
 
   if (blocks.length === 1) {
-    return <div className={styles.tabs}>{blocks[0].content}</div>;
+    return (
+      <div className={`${styles.tabs} [&_[data-slot=code-block-header]]:hidden`}>
+        {blocks[0].content}
+      </div>
+    );
   }
 
   return (
     <TabsPrimitive
       value={selected}
       onValueChange={setSelectedKey}
-      className="my-4 gap-0 overflow-hidden rounded-lg bg-card [&_[data-slot=code-block]]:my-0 [&_[data-slot=code-block]]:rounded-none [&_[data-slot=code-block]]:border-0 [&_[data-slot=code-block]]:bg-transparent"
+      className="my-4 gap-0 overflow-hidden rounded-lg bg-card [&_[data-slot=code-block]]:my-0 [&_[data-slot=code-block]]:rounded-none [&_[data-slot=code-block]]:border-0 [&_[data-slot=code-block]]:bg-transparent [&_[data-slot=code-block-header]]:hidden"
     >
       <TabsList
         variant="line"

package/src/entry-server.tsx

@@ -11,6 +11,7 @@ import {
   getLocaleByPathname,
   getRedirects,
   getSeo,
+  siteConfig,
   siteName,
   standalonePages,
 } from '@/lib/site-config';
@@ -27,6 +28,13 @@ export interface SitemapEntry {
   lastmod?: string;
 }
 
+export interface LlmsPage {
+  route: string;
+  filePath: string;
+  title: string;
+  description?: string;
+}
+
 /** Base-relative routes for every scope. The prerenderer prepends the deploy base itself. */
 export function getRoutes(): string[] {
   return [...docsSite.pages.map(page => page.url), ...standalonePages.map(page => page.path)];
@@ -51,6 +59,46 @@ export function getMarkdownPages(): { route: string; filePath: string }[] {
   ];
 }
 
+/** Navigable Markdown pages used to generate llms.txt and llms-full.txt. */
+export function getLlmsPages(): LlmsPage[] {
+  const { indexing } = getSeo();
+  const pages: LlmsPage[] = [];
+
+  for (const page of docsSite.pages) {
+    const doc = getDocModule(page.filePath);
+
+    if (
+      doc?.frontmatter?.noindex === true ||
+      ((page.hidden || getScopeForPage(docsSite, page).hidden) && indexing !== 'all')
+    ) {
+      continue;
+    }
+
+    pages.push({
+      route: page.url,
+      filePath: page.filePath,
+      title: doc?.frontmatter?.title || page.label,
+      description: doc?.frontmatter?.description,
+    });
+  }
+
+  for (const page of standalonePages) {
+    if (page.filePath.endsWith('.tsx')) continue;
+
+    const doc = getDocModule(page.filePath);
+    if (doc?.frontmatter?.noindex === true) continue;
+
+    pages.push({
+      route: page.path,
+      filePath: page.filePath,
+      title: doc?.frontmatter?.title || page.title || page.path,
+      description: doc?.frontmatter?.description,
+    });
+  }
+
+  return pages;
+}
+
 /**
  * Absolute URLs for the sitemap, honoring `seo.indexing` and per-page
  * noindex. Empty when the shiso.config `siteUrl` is not configured, since a sitemap
@@ -106,4 +154,6 @@ export function render(url: string): RenderResult {
   return { html, head: renderHeadToString(buildHead(url)), htmlAttrs: getLocaleByPathname(url) };
 }
 
+export const siteDescription = siteConfig.description;
+
 export { docsHomeUrl, siteName };

package/src/lib/code-blocks.ts

@@ -0,0 +1,18 @@
+// Relative import: this module is also loaded by vite.config.ts, which esbuild
+// bundles without applying the '@/' resolve alias.
+import type { ResolvedCodeBlockConfig, StylingConfig } from './types.ts';
+
+export const DEFAULT_CODE_THEME = { light: 'github-light', dark: 'github-dark' } as const;
+
+/** Applies defaults to `styling.codeBlocks` from docs.json. */
+export function resolveCodeBlockConfig(styling?: StylingConfig): ResolvedCodeBlockConfig {
+  const codeBlocks = styling?.codeBlocks;
+
+  return {
+    lineNumbers: codeBlocks?.lineNumbers === true,
+    theme: {
+      light: codeBlocks?.theme?.light || DEFAULT_CODE_THEME.light,
+      dark: codeBlocks?.theme?.dark || DEFAULT_CODE_THEME.dark,
+    },
+  };
+}

package/src/lib/code-meta.ts

@@ -0,0 +1,87 @@
+/**
+ * Parses the fenced code meta string (the text after the language tag) into
+ * the directives Shiso understands:
+ *
+ *   ```ts title="app.ts" {1,3-5} showLineNumbers=10
+ *
+ * Anything unrecognized becomes the title, so the bare label form used by
+ * `CodeGroup` (```bash npm) keeps working.
+ */
+
+export interface CodeMeta {
+  title?: string;
+  highlightLines: number[];
+  showLineNumbers?: boolean;
+  startLine?: number;
+  /** Unrecognized tokens, in order. */
+  rest: string[];
+}
+
+/** Splits on whitespace while keeping quoted segments (title="my file.ts") intact. */
+function tokenize(meta: string): string[] {
+  return meta.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) || [];
+}
+
+function parseLineList(list: string): number[] {
+  const lines = new Set<number>();
+
+  for (const part of list.split(',')) {
+    const range = part.trim();
+    if (!range) {
+      continue;
+    }
+
+    const [from, to = from] = range.split('-').map(Number);
+    if (!Number.isInteger(from) || from < 1 || !Number.isInteger(to)) {
+      continue;
+    }
+
+    for (let line = from; line <= to; line += 1) {
+      lines.add(line);
+    }
+  }
+
+  return [...lines].sort((a, b) => a - b);
+}
+
+function unquote(value: string): string {
+  return value.replace(/^(["'])(.*)\1$/, '$2');
+}
+
+export function parseCodeMeta(meta: string | undefined): CodeMeta {
+  const result: CodeMeta = { highlightLines: [], rest: [] };
+  const lines = new Set<number>();
+
+  for (const token of tokenize((meta || '').trim())) {
+    const highlight = token.match(/^\{([\d,\s-]+)\}$/);
+    const title = token.match(/^title=(.+)$/);
+    const numbered = token.match(/^showLineNumbers(?:=(\d+))?$/);
+
+    if (highlight) {
+      for (const line of parseLineList(highlight[1])) {
+        lines.add(line);
+      }
+    } else if (title) {
+      result.title = unquote(title[1]);
+    } else if (numbered) {
+      result.showLineNumbers = true;
+      if (numbered[1]) {
+        result.startLine = Number(numbered[1]);
+      }
+    } else if (token === 'hideLineNumbers') {
+      result.showLineNumbers = false;
+    } else {
+      result.rest.push(unquote(token));
+    }
+  }
+
+  result.highlightLines = [...lines].sort((a, b) => a - b);
+
+  // Back-compat: a bare label (```bash npm) is the title, which CodeGroup uses
+  // as the tab name.
+  if (!result.title && result.rest.length) {
+    result.title = result.rest.join(' ');
+  }
+
+  return result;
+}

package/src/lib/docs-config.ts

@@ -391,6 +391,7 @@ interface PendingPage {
   hidden?: boolean;
   icon?: string;
   tag?: string;
+  method?: string;
 }
 
 type PendingNode =
@@ -424,7 +425,7 @@ function addPage(
   pageRef: string,
   context: WalkContext,
   state: WalkState,
-  extra: { label?: string; icon?: string; tag?: string; hidden?: boolean } = {},
+  extra: { label?: string; icon?: string; tag?: string; method?: string; hidden?: boolean } = {},
 ): number {
   const { fileSlug, slug } = normalizePageReference(pageRef);
   const order = state.order.value++;
@@ -440,6 +441,7 @@ function addPage(
     hidden: extra.hidden || context.hidden || undefined,
     icon: extra.icon,
     tag: extra.tag,
+    method: extra.method,
   });
 
   return order;
@@ -497,6 +499,7 @@ function collectPages(items: PageItem[], context: WalkContext, state: WalkState)
           label,
           icon: typeof item.icon === 'string' ? item.icon : undefined,
           tag: typeof item.tag === 'string' ? item.tag : undefined,
+          method: typeof item.method === 'string' ? item.method : undefined,
           hidden: item.hidden === true,
         }),
       });

package/src/lib/openapi.generated.ts

@@ -0,0 +1,4 @@
+// Build-time alias target. Shiso replaces this module with the project's generated operations.
+import type { NormalizedOperation } from '@/lib/types';
+
+export const OPENAPI_OPERATIONS: Record<string, NormalizedOperation> = {};

package/src/lib/openapi.ts

@@ -0,0 +1,63 @@
+/**
+ * Runtime helpers for OpenAPI reference pages. Operation data is produced at
+ * build time by scripts/generate-openapi.mjs and reaches the client through
+ * the aliased openapi.generated module.
+ */
+
+import type { BadgeColor } from '@/components/docs/Badge';
+import { OPENAPI_OPERATIONS } from '@/lib/openapi.generated';
+import { createSlugger } from '@/lib/slug';
+import type { NormalizedOperation, TocEntry } from '@/lib/types';
+
+export const METHOD_COLORS: Record<string, BadgeColor> = {
+  GET: 'green',
+  POST: 'blue',
+  PUT: 'orange',
+  PATCH: 'purple',
+  DELETE: 'red',
+};
+
+export function methodColor(method?: string): BadgeColor {
+  return (method && METHOD_COLORS[method.toUpperCase()]) || 'gray';
+}
+
+export function statusColor(status: string): BadgeColor {
+  if (status.startsWith('2')) return 'green';
+  if (status.startsWith('3')) return 'blue';
+  if (status.startsWith('4') || status.startsWith('5')) return 'red';
+  return 'gray';
+}
+
+/** Looks up the operation bound by an `openapi:` frontmatter value. */
+export function getOperation(key?: unknown): NormalizedOperation | undefined {
+  if (typeof key !== 'string' || !key.trim()) {
+    return undefined;
+  }
+
+  const [method, ...rest] = key.trim().split(/\s+/);
+  return OPENAPI_OPERATIONS[`${method.toUpperCase()} ${rest.join(' ')}`];
+}
+
+export function hasParameters(operation: NormalizedOperation): boolean {
+  const { query, path, header, cookie } = operation.parameters;
+  return (
+    query.length + path.length + header.length + cookie.length > 0 || operation.security.length > 0
+  );
+}
+
+/**
+ * Section headings for an operation, in render order. The single source of
+ * truth for section ids: the component, the table of contents, the content
+ * checker, and the search indexer all derive their anchors from these labels.
+ */
+export function operationSections(operation: NormalizedOperation): TocEntry[] {
+  const slugger = createSlugger();
+  const names = [
+    hasParameters(operation) ? 'Parameters' : undefined,
+    operation.requestBody ? 'Request body' : undefined,
+    operation.responses.length ? 'Responses' : undefined,
+    operation.samples.length ? 'Code samples' : undefined,
+  ].filter((name): name is string => Boolean(name));
+
+  return names.map(name => ({ name, id: slugger.slug(name), size: 2 }));
+}