@umami/shiso 1.11.0 → 1.13.0

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/components.d.ts

@@ -211,6 +211,85 @@ export interface TooltipProps {
 
 export declare function Tooltip(props: TooltipProps): ReactElement;
 
+export interface UpdateRss {
+  title?: string;
+  description?: string;
+}
+
+export interface UpdateProps {
+  label: string;
+  description?: ReactNode;
+  tags?: string[];
+  rss?: UpdateRss;
+  children?: ReactNode;
+}
+
+export declare function Update(props: UpdateProps): ReactElement;
+
+export interface ChangelogProps {
+  children?: ReactNode;
+}
+
+export declare function Changelog(props: ChangelogProps): ReactElement;
+
+export type MermaidPlacement = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+export interface MermaidProps {
+  chart?: string;
+  title?: ReactNode;
+  actions?: boolean;
+  placement?: MermaidPlacement;
+  children?: ReactNode;
+}
+
+export declare function Mermaid(props: MermaidProps): ReactElement;
+
+export interface PanelProps {
+  children?: ReactNode;
+}
+
+export declare function Panel(props: PanelProps): ReactElement;
+
+export interface TileProps {
+  href: string;
+  title?: ReactNode;
+  description?: ReactNode;
+  children: ReactNode;
+  target?: '_self' | '_blank';
+}
+
+export interface TilesProps {
+  children?: ReactNode;
+  cols?: 1 | 2 | 3 | 4;
+}
+
+export declare function Tile(props: TileProps): ReactElement;
+export declare function Tiles(props: TilesProps): ReactElement;
+
+export interface TreeFolderProps {
+  name: string;
+  defaultOpen?: boolean;
+  openable?: boolean;
+  highlight?: boolean;
+  children?: ReactNode;
+}
+
+export interface TreeFileProps {
+  name: string;
+  highlight?: boolean;
+}
+
+export interface TreeProps {
+  children?: ReactNode;
+  style?: React.CSSProperties;
+  className?: string;
+}
+
+export declare function Tree(props: TreeProps): ReactElement;
+export declare function FileTree(props: TreeProps): ReactElement;
+export declare function TreeFolder(props: TreeFolderProps): ReactElement;
+export declare function TreeFile(props: TreeFileProps): ReactElement;
+
 export interface ZoomableImageProps extends ImgHTMLAttributes<HTMLImageElement> {
   noZoom?: boolean;
 }

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'),