@umami/shiso 1.11.0 → 1.12.0

package/src/lib/rehype-shiki.ts

@@ -0,0 +1,196 @@
+/**
+ * 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 lang = resolveLanguage(requested);
+  const meta = parseCodeMeta(typeof code.data?.meta === 'string' ? code.data.meta : '');
+  // 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 || [],

package/src/lib/types.ts

@@ -1,3 +1,5 @@
+import type { PluggableList } from 'unified';
+
 /* ---------------------------------------------------------------------------
  * Raw docs.json shapes
  * ------------------------------------------------------------------------- */
@@ -8,6 +10,8 @@ export interface PageObjectItem {
   label?: string;
   icon?: string;
   tag?: string;
+  /** HTTP method badge shown in the sidebar, set by OpenAPI navigation entries. */
+  method?: string;
   hidden?: boolean;
 }
 
@@ -21,7 +25,12 @@ export interface LinkItem {
   target?: LinkTarget;
 }
 
-export type PageItem = string | GroupItem | PageObjectItem | LinkItem;
+export interface GlobItem {
+  glob: string;
+  exclude?: string[];
+}
+
+export type PageItem = string | GroupItem | PageObjectItem | LinkItem | GlobItem;
 
 export interface GroupItem {
   group: string;
@@ -113,6 +122,11 @@ export type LogoOption =
 
 /** Project-level settings supplied by shiso.config.ts. Mirrors the public
  * shape exported from "@umami/shiso/config". */
+export interface MdxConfig {
+  remarkPlugins?: PluggableList;
+  rehypePlugins?: PluggableList;
+}
+
 export interface ShisoConfig {
   /** Where docs pages are mounted within the site. Default "/docs"; "" for root. */
   docsPrefix?: string;
@@ -122,6 +136,8 @@ export interface ShisoConfig {
   siteUrl?: string;
   /** Locale used for deterministic date formatting. */
   locale?: string;
+  /** Build-time remark and rehype plugins. */
+  mdx?: MdxConfig;
 }
 
 /** ShisoConfig after defaults and normalization, as served by `virtual:shiso-config`. */
@@ -130,6 +146,8 @@ export interface ResolvedShisoConfig {
   contentDir: string;
   siteUrl?: string;
   locale: string;
+  /** Build-only compiler hooks. Removed from the virtual browser module. */
+  mdx?: MdxConfig;
 }
 
 export type LinkTarget = '_self' | '_blank';
@@ -236,9 +254,26 @@ export interface AppearanceConfig {
   strict?: boolean;
 }
 
+export interface CodeBlockConfig {
+  /** Show line numbers on every block. Override per block with `showLineNumbers` or `hideLineNumbers`. */
+  lineNumbers?: boolean;
+  /** Bundled Shiki theme names for each color mode. */
+  theme?: {
+    light?: string;
+    dark?: string;
+  };
+}
+
 export interface StylingConfig {
   /** Page eyebrow style: the section name (default) or the full breadcrumb path. */
   eyebrows?: 'section' | 'breadcrumbs';
+  /** Fenced code block defaults. */
+  codeBlocks?: CodeBlockConfig;
+}
+
+export interface ResolvedCodeBlockConfig {
+  lineNumbers: boolean;
+  theme: { light: string; dark: string };
 }
 
 export interface FontSpec {
@@ -345,6 +380,15 @@ export interface DocsConfig {
   search?: false | SearchConfig;
   interaction?: InteractionConfig;
   contextual?: ContextualConfig;
+  /** API reference settings: the OpenAPI spec powering `openapi:` frontmatter pages. */
+  api?: ApiConfig;
+}
+
+export interface ApiConfig {
+  /** Path to a local OpenAPI 3.x spec (JSON or YAML), relative to the project root. */
+  spec: string;
+  /** Folder inside the content directory for generated endpoint pages. Default "api-reference". */
+  directory?: string;
 }
 
 /* ---------------------------------------------------------------------------
@@ -387,6 +431,8 @@ export interface NormalizedDocsPage {
   tag?: string;
   /** Module key of the MDX file, e.g. "/content/docs/installation.mdx". */
   filePath: string;
+  /** HTTP method badge for API reference pages. */
+  method?: string;
 }
 
 /** A routed docs page in the navigation tree. */
@@ -530,7 +576,10 @@ export interface SiteModel {
   footer: NormalizedFooter | null;
   banner: BannerConfig | null;
   appearance: Required<AppearanceConfig>;
-  styling: Required<Pick<StylingConfig, 'eyebrows'>>;
+  styling: {
+    eyebrows: 'section' | 'breadcrumbs';
+    codeBlocks: ResolvedCodeBlockConfig;
+  };
   search: import('@/lib/search/config').ResolvedSearchConfig;
   contextualOptions: ContextualOption[];
   error404: Required<Pick<Error404Config, 'redirect'>> & Error404Config;
@@ -574,6 +623,8 @@ export interface DocFrontmatter {
   timestamp?: boolean;
   /** Related pages rendered above the prev/next pager. */
   related?: RelatedEntry[];
+  /** Binds the page to an API operation, e.g. "GET /users/{id}". */
+  openapi?: string;
   [key: string]: unknown;
 }
 
@@ -582,3 +633,66 @@ export interface DocModule {
   frontmatter?: DocFrontmatter;
   toc?: TocEntry[];
 }
+
+/* ---------------------------------------------------------------------------
+ * OpenAPI reference shapes (produced by scripts/lib/openapi.mjs)
+ * ------------------------------------------------------------------------- */
+
+export interface SchemaNode {
+  name?: string;
+  /** Display label such as "string", "User[]", "enum<string>", or "oneOf". */
+  type: string;
+  required?: boolean;
+  deprecated?: boolean;
+  description?: string;
+  default?: string;
+  enum?: string[];
+  children?: SchemaNode[];
+}
+
+export interface OpenApiSample {
+  language: string;
+  label: string;
+  source: string;
+  /** Shiki-highlighted markup generated at build time. */
+  html?: string;
+  lineCount?: number;
+}
+
+export interface OpenApiResponse {
+  status: string;
+  description?: string;
+  contentType?: string;
+  schema?: SchemaNode;
+  example?: string;
+  exampleHtml?: string;
+}
+
+export interface NormalizedOperation {
+  id: string;
+  /** Frontmatter lookup key, e.g. "GET /users/{id}". */
+  key: string;
+  method: string;
+  path: string;
+  summary?: string;
+  description?: string;
+  tags: string[];
+  deprecated?: boolean;
+  parameters: {
+    query: SchemaNode[];
+    path: SchemaNode[];
+    header: SchemaNode[];
+    cookie: SchemaNode[];
+  };
+  requestBody?: {
+    required?: boolean;
+    contentType: string;
+    schema: SchemaNode;
+    example?: string;
+    exampleHtml?: string;
+  };
+  responses: OpenApiResponse[];
+  security: string[];
+  serverUrl: string;
+  samples: OpenApiSample[];
+}

package/src/styles/global.css

@@ -256,88 +256,78 @@
   }
 }
 
-/* These rules are unlayered so they can override Highlight.js's unlayered theme. */
-
-code.hljs {
-  background: transparent;
-}
-
-/* The scroll area owns code-block overflow and padding. */
-pre.code-block code.hljs {
-  overflow: visible;
-  padding: 0;
-}
-
-/* GitHub Dark syntax colors, scoped so the default GitHub theme stays light. */
-[data-theme="dark"] .hljs {
-  color: #c9d1d9;
-}
+@layer components {
+  /* Shiki output: one inline-block per line so highlight and diff bands span the
+     full scroll width. Line numbers and diff markers are pseudo-elements, which
+     keeps them out of the copy button, text selection, and the search index. */
+  .code-block .line {
+    position: relative;
+    display: inline-block;
+    box-sizing: border-box;
+    min-width: 100%;
+    min-height: 1lh;
+    padding-inline: 0.75rem 3rem;
+  }
 
-[data-theme="dark"]
-  :is(
-    .hljs-doctag,
-    .hljs-keyword,
-    .hljs-meta .hljs-keyword,
-    .hljs-template-tag,
-    .hljs-template-variable,
-    .hljs-type,
-    .hljs-variable.language_
-  ) {
-  color: #ff7b72;
-}
+  .code-block .line span {
+    color: var(--shiki-light);
+    font-style: var(--shiki-light-font-style, inherit);
+    font-weight: var(--shiki-light-font-weight, inherit);
+    text-decoration: var(--shiki-light-text-decoration, inherit);
+  }
 
-[data-theme="dark"]
-  :is(.hljs-title, .hljs-title.class_, .hljs-title.class_.inherited__, .hljs-title.function_) {
-  color: #d2a8ff;
-}
+  [data-theme="dark"] .code-block .line span {
+    color: var(--shiki-dark);
+    font-style: var(--shiki-dark-font-style, inherit);
+    font-weight: var(--shiki-dark-font-weight, inherit);
+    text-decoration: var(--shiki-dark-text-decoration, inherit);
+  }
 
-[data-theme="dark"]
-  :is(
-    .hljs-attr,
-    .hljs-attribute,
-    .hljs-literal,
-    .hljs-meta,
-    .hljs-number,
-    .hljs-operator,
-    .hljs-variable,
-    .hljs-selector-attr,
-    .hljs-selector-class,
-    .hljs-selector-id,
-    .hljs-section
-  ) {
-  color: #79c0ff;
-}
+  .code-block .line[data-highlighted] {
+    background: color-mix(in srgb, var(--primary) 10%, transparent);
+    box-shadow: inset 2px 0 var(--primary);
+  }
 
-[data-theme="dark"] :is(.hljs-regexp, .hljs-string, .hljs-meta .hljs-string) {
-  color: #a5d6ff;
-}
+  .code-block .line[data-diff="add"] {
+    background: color-mix(in srgb, #3fb950 14%, transparent);
+  }
 
-[data-theme="dark"] :is(.hljs-built_in, .hljs-symbol) {
-  color: #ffa657;
-}
+  .code-block .line[data-diff="remove"] {
+    background: color-mix(in srgb, #f85149 14%, transparent);
+  }
 
-[data-theme="dark"] :is(.hljs-comment, .hljs-code, .hljs-formula) {
-  color: #8b949e;
-}
+  .code-block[data-diff-markers] .line {
+    padding-inline-start: 1.5rem;
+  }
 
-[data-theme="dark"] :is(.hljs-name, .hljs-quote, .hljs-selector-tag, .hljs-selector-pseudo) {
-  color: #7ee787;
-}
+  .code-block[data-diff-markers] .line[data-diff]::after {
+    position: absolute;
+    top: 0;
+    left: 0.5rem;
+    color: var(--muted-foreground);
+    user-select: none;
+  }
 
-[data-theme="dark"] :is(.hljs-subst, .hljs-emphasis, .hljs-strong) {
-  color: #c9d1d9;
-}
+  .code-block[data-diff-markers] .line[data-diff="add"]::after {
+    content: "+";
+  }
 
-[data-theme="dark"] .hljs-bullet {
-  color: #f2cc60;
-}
+  .code-block[data-diff-markers] .line[data-diff="remove"]::after {
+    content: "-";
+  }
 
-[data-theme="dark"] .hljs-addition {
-  color: #aff5b4;
-  background-color: #033a16;
-}
+  /* `counter-reset` is set inline by CodeBlock so blocks can start at any line. */
+  .code-block[data-line-numbers] .line {
+    counter-increment: line;
+  }
 
-[data-theme="dark"] .hljs-deletion {
-  color: #ffdcd7;
-  background-color: #67060c;
+  .code-block[data-line-numbers] .line::before {
+    content: counter(line);
+    display: inline-block;
+    width: var(--code-gutter, 2ch);
+    margin-inline-end: 1rem;
+    color: var(--muted-foreground);
+    text-align: right;
+    user-select: none;
+  }
 }

package/types/config.d.ts

@@ -1,7 +1,12 @@
-/**
- * Public types for shiso.config.ts. Kept self-contained (no imports) so the
- * config file typechecks in consuming projects without pulling in the runtime.
- */
+import type { PluggableList } from 'unified';
+
+/** Build-time Markdown and MDX compiler extensions. */
+export interface MdxConfig {
+  /** Unified remark plugins, run before Shiso's code-title and table-of-contents transforms. */
+  remarkPlugins?: PluggableList;
+  /** Unified rehype plugins, run before Shiso's highlighting, image, and heading transforms. */
+  rehypePlugins?: PluggableList;
+}
 
 /** Project-level settings supplied by shiso.config.ts. All fields are optional. */
 export interface ShisoConfig {
@@ -13,6 +18,8 @@ export interface ShisoConfig {
   siteUrl?: string;
   /** Locale used for deterministic date formatting. Default "en-US". */
   locale?: string;
+  /** Build-time remark and rehype plugins for Markdown and MDX content. */
+  mdx?: MdxConfig;
 }
 
 /** Identity helper that types a shiso.config.ts default export. */

package/vite.config.ts

@@ -7,8 +7,10 @@ import { defineConfig, type Plugin, searchForWorkspaceRoot } from 'vite';
 import { shisoMdx } from './mdx.config.ts';
 import { generateIconRegistry } from './scripts/generate-icon-registry.mjs';
 import { shisoLastModified } from './scripts/generate-last-modified.mjs';
+import { generateOpenApiModule } from './scripts/generate-openapi.mjs';
 import { generateSearchIndex } from './scripts/generate-search-index.mjs';
 import { createDocsConfigModule } from './scripts/vite-docs-config.mjs';
+import { resolveCodeBlockConfig } from './src/lib/code-blocks.ts';
 import type { DocsConfig, ResolvedShisoConfig } from './src/lib/types.ts';
 
 /**
@@ -37,6 +39,34 @@ function shisoIconRegistry(getDocsConfig: () => DocsConfig, root: string, output
  * Keeps src/lib/search-index.generated.ts in sync with content, so the search
  * dialog can query page text without a server.
  */
+function shisoOpenApi(
+  getDocsConfig: () => DocsConfig,
+  getSpecPath: () => string | undefined,
+  root: string,
+  output: string,
+): Plugin {
+  const generate = () =>
+    generateOpenApiModule({
+      root,
+      config: getDocsConfig(),
+      theme: resolveCodeBlockConfig(getDocsConfig().styling).theme,
+      output,
+    });
+
+  return {
+    name: 'shiso-openapi',
+    async buildStart() {
+      await generate();
+    },
+    async handleHotUpdate({ file }) {
+      const specPath = getSpecPath();
+      if ((specPath && path.resolve(file) === specPath) || file.endsWith('docs.json')) {
+        await generate();
+      }
+    },
+  };
+}
+
 function shisoSearchIndex(
   getDocsConfig: () => DocsConfig,
   getShisoConfig: () => ResolvedShisoConfig,
@@ -221,8 +251,11 @@ function buildThemeCss(config: DocsConfig): string {
   }
 
   return [
-    root.length ? `:root{${root.join('')}}` : '',
-    dark.length ? `[data-theme="dark"]{${dark.join('')}}` : '',
+    // App styles are loaded by the client entry after this head style in dev.
+    // Use a more specific selector than the default token declarations so
+    // configured theme values win regardless of stylesheet load order.
+    root.length ? `html:root{${root.join('')}}` : '',
+    dark.length ? `html[data-theme="dark"]{${dark.join('')}}` : '',
     ...extra,
   ]
     .filter(Boolean)
@@ -459,9 +492,18 @@ export default defineConfig(async () => {
         projectRoot,
         path.join(generatedRoot, 'search-index.generated.ts'),
       ),
+      shisoOpenApi(
+        getDocsConfig,
+        () => configModule.getSpecPath?.(),
+        projectRoot,
+        path.join(generatedRoot, 'openapi.generated.ts'),
+      ),
       shisoHtml(getDocsConfig),
       shisoMarkdownDev(getDocsConfig, getShisoConfig, projectRoot),
-      shisoMdx(),
+      shisoMdx({
+        ...getShisoConfig().mdx,
+        codeBlocks: resolveCodeBlockConfig(getDocsConfig().styling),
+      }),
       react({ include: /\.(mdx|md|tsx|ts|jsx|js)$/ }),
     ],
     resolve: {
@@ -476,6 +518,10 @@ export default defineConfig(async () => {
           find: '@/lib/search-index.generated',
           replacement: path.join(generatedRoot, 'search-index.generated.ts'),
         },
+        {
+          find: '@/lib/openapi.generated',
+          replacement: path.join(generatedRoot, 'openapi.generated.ts'),
+        },
         {
           find: '@/generated/last-modified',
           replacement: path.join(generatedRoot, 'last-modified.ts'),