@umami/shiso 1.11.0 → 1.13.0

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 }));
+}

package/src/lib/rehype-shiki.ts

@@ -0,0 +1,213 @@
+/**
+ * Highlights fenced code blocks with Shiki at build time.
+ *
+ * Output contract (consumed by `components/CodeBlock.tsx` and global.css):
+ * - `<pre>` carries `data-language`, and when present `data-title`,
+ *   `data-line-numbers`, `data-line-start`, `data-line-count`, `data-diff-markers`.
+ * - `<code class="language-x">` keeps its class; its children are Shiki's
+ *   `<span class="line">` elements, each optionally marked `data-highlighted`
+ *   or `data-diff="add|remove"`.
+ * - Token spans carry only `--shiki-light` / `--shiki-dark` variables so the
+ *   markup is identical in both color modes and CSS picks the theme.
+ */
+
+import { transformerNotationDiff, transformerNotationHighlight } from '@shikijs/transformers';
+import {
+  bundledLanguages,
+  bundledThemes,
+  createHighlighter,
+  type Highlighter,
+  type ShikiTransformer,
+} from 'shiki';
+// Relative imports: this module is also loaded by vite.config.ts, which esbuild
+// bundles without applying the '@/' resolve alias.
+import { parseCodeMeta } from './code-meta.ts';
+import { type MdNode, toText, walkTree } from './mdast.ts';
+import type { ResolvedCodeBlockConfig } from './types.ts';
+
+type Properties = Record<string, unknown>;
+
+const highlighters = new Map<string, Promise<Highlighter>>();
+const languageLoads = new Map<string, Promise<void>>();
+const warnedLanguages = new Set<string>();
+
+function assertTheme(name: string, key: 'light' | 'dark') {
+  if (!(name in bundledThemes)) {
+    throw new Error(
+      `[shiso] Unknown code theme "${name}" in docs.json styling.codeBlocks.theme.${key}. ` +
+        'Use a bundled Shiki theme name (https://shiki.style/themes).',
+    );
+  }
+}
+
+function getHighlighter(theme: ResolvedCodeBlockConfig['theme']): Promise<Highlighter> {
+  const key = `${theme.light}|${theme.dark}`;
+  let highlighter = highlighters.get(key);
+
+  if (!highlighter) {
+    assertTheme(theme.light, 'light');
+    assertTheme(theme.dark, 'dark');
+    highlighter = createHighlighter({ themes: [theme.light, theme.dark], langs: [] });
+    highlighters.set(key, highlighter);
+  }
+
+  return highlighter;
+}
+
+async function ensureLanguage(highlighter: Highlighter, lang: string) {
+  if (highlighter.getLoadedLanguages().includes(lang)) {
+    return;
+  }
+
+  let load = languageLoads.get(lang);
+  if (!load) {
+    load = highlighter.loadLanguage(lang as keyof typeof bundledLanguages);
+    languageLoads.set(lang, load);
+  }
+
+  await load;
+}
+
+function resolveLanguage(requested: string | undefined): string {
+  if (!requested || requested === 'text' || requested === 'plaintext' || requested === 'txt') {
+    return 'text';
+  }
+
+  if (requested in bundledLanguages) {
+    return requested;
+  }
+
+  if (!warnedLanguages.has(requested)) {
+    warnedLanguages.add(requested);
+    console.warn(`[shiso] No syntax grammar for "${requested}"; rendering it as plain text.`);
+  }
+
+  return 'text';
+}
+
+/** Marks meta `{1,3-5}` lines and, for `diff` blocks, the added/removed lines. */
+function shisoLineMarks(highlight: Set<number>, diffLanguage: boolean): ShikiTransformer {
+  return {
+    name: 'shiso:line-marks',
+    line(node, line) {
+      if (highlight.has(line)) {
+        node.properties['data-highlighted'] = '';
+      }
+
+      if (diffLanguage) {
+        const text = toText(node as unknown as MdNode);
+        if (/^\+(?!\+\+)/.test(text)) {
+          node.properties['data-diff'] = 'add';
+        } else if (/^-(?!--)/.test(text)) {
+          node.properties['data-diff'] = 'remove';
+        }
+      }
+    },
+  };
+}
+
+/** Converts transformer classes (`highlighted`, `diff add|remove`) into data attributes. */
+function normalizeLine(line: MdNode) {
+  const properties = (line.properties || {}) as Properties;
+  // Shiki transformers write `class`; mdast-util-to-hast writes `className`.
+  const classes = [properties.class, properties.className]
+    .flatMap(value => (Array.isArray(value) ? value : String(value || '').split(' ')))
+    .map(String)
+    .filter(Boolean);
+
+  if (classes.includes('highlighted')) {
+    properties['data-highlighted'] = '';
+  }
+  if (classes.includes('diff')) {
+    properties['data-diff'] = classes.includes('remove') ? 'remove' : 'add';
+  }
+
+  delete properties.class;
+  properties.className = ['line'];
+  line.properties = properties;
+}
+
+async function highlightBlock(pre: MdNode, code: MdNode, config: ResolvedCodeBlockConfig) {
+  const codeProperties = (code.properties || {}) as Properties;
+  const classes = Array.isArray(codeProperties.className)
+    ? codeProperties.className.map(String)
+    : [];
+  const requested = classes.map(value => value.match(/^language-(\S+)$/)?.[1]).find(Boolean);
+  const meta = parseCodeMeta(typeof code.data?.meta === 'string' ? code.data.meta : '');
+
+  // Mermaid diagrams render client-side via the <Mermaid> component; keep the
+  // raw definition so CodeBlock can hand it over untouched.
+  if (requested === 'mermaid') {
+    const metaRaw = typeof code.data?.meta === 'string' ? code.data.meta : '';
+    const placement = metaRaw.match(/placement=["'](top-left|top-right|bottom-left|bottom-right)["']/)?.[1];
+    const actions = metaRaw.match(/actions=\{(true|false)\}/)?.[1];
+    pre.properties = {
+      ...(pre.properties as Properties),
+      'data-language': 'mermaid',
+      ...(meta.title ? { 'data-title': meta.title } : {}),
+      ...(placement ? { 'data-placement': placement } : {}),
+      ...(actions ? { 'data-actions': actions } : {}),
+    };
+    return;
+  }
+
+  const lang = resolveLanguage(requested);
+  // mdast-util-to-hast appends a trailing newline to the code text.
+  const source = toText(code).replace(/\n$/, '');
+
+  const highlighter = await getHighlighter(config.theme);
+  if (lang !== 'text') {
+    await ensureLanguage(highlighter, lang);
+  }
+
+  const hast = highlighter.codeToHast(source, {
+    lang,
+    themes: config.theme,
+    defaultColor: false,
+    transformers: [
+      transformerNotationHighlight({ matchAlgorithm: 'v3' }),
+      transformerNotationDiff({ matchAlgorithm: 'v3' }),
+      shisoLineMarks(new Set(meta.highlightLines), lang === 'diff'),
+    ],
+  }) as MdNode;
+
+  // root > pre > code
+  const shikiPre = hast.children?.[0] as MdNode;
+  const shikiCode = shikiPre?.children?.[0] as MdNode;
+  const lines = (shikiCode?.children || []).filter(node => node.tagName === 'span');
+  lines.forEach(normalizeLine);
+
+  const hasNotationDiff =
+    lang !== 'diff' && lines.some(line => (line.properties as Properties)['data-diff']);
+  const showLineNumbers = meta.showLineNumbers ?? config.lineNumbers;
+
+  code.children = shikiCode?.children || [];
+  pre.properties = {
+    ...(pre.properties as Properties),
+    'data-language': lang,
+    ...(meta.title ? { 'data-title': meta.title } : {}),
+    ...(showLineNumbers ? { 'data-line-numbers': 'true' } : {}),
+    ...(meta.startLine ? { 'data-line-start': String(meta.startLine) } : {}),
+    'data-line-count': String(lines.length),
+    ...(hasNotationDiff ? { 'data-diff-markers': 'true' } : {}),
+  };
+}
+
+export function rehypeShiki(config: ResolvedCodeBlockConfig) {
+  return async (tree: MdNode) => {
+    const tasks: Promise<void>[] = [];
+
+    walkTree(tree, pre => {
+      if (pre.tagName !== 'pre') {
+        return;
+      }
+
+      const code = pre.children?.find(child => child.tagName === 'code');
+      if (code) {
+        tasks.push(highlightBlock(pre, code, config));
+      }
+    });
+
+    await Promise.all(tasks);
+  };
+}

package/src/lib/site-model.ts

@@ -1,3 +1,4 @@
+import { resolveCodeBlockConfig } from '@/lib/code-blocks';
 import { toAbsoluteUrl, toHref } from '@/lib/paths';
 import { resolveSearchConfig } from '@/lib/search/config';
 import type {
@@ -130,6 +131,7 @@ export function resolveSiteModel(
     },
     styling: {
       eyebrows: config.styling?.eyebrows === 'breadcrumbs' ? 'breadcrumbs' : 'section',
+      codeBlocks: resolveCodeBlockConfig(config.styling),
     },
     search: resolveSearchConfig(config.search),
     contextualOptions: config.contextual?.options || [],