@umami/shiso 1.17.0 → 1.19.0

package/src/lib/types.ts

@@ -1,3 +1,7 @@
+import type { ThemeLabels, Translations } from '../../types/labels';
+
+export type { ThemeLabels, Translations } from '../../types/labels';
+
 import type { PluggableList } from 'unified';
 
 /* ---------------------------------------------------------------------------
@@ -134,8 +138,10 @@ export interface ShisoConfig {
   contentDir?: string;
   /** Absolute site origin, required for canonical and og:url tags. */
   siteUrl?: string;
-  /** Locale used for deterministic date formatting. */
+  /** Default locale for UI labels and date formatting. */
   locale?: string;
+  /** Partial UI label overrides keyed by BCP 47 locale. */
+  translations?: Translations;
   /** Build-time remark and rehype plugins. */
   mdx?: MdxConfig;
 }
@@ -146,6 +152,7 @@ export interface ResolvedShisoConfig {
   contentDir: string;
   siteUrl?: string;
   locale: string;
+  translations?: Translations;
   /** Build-only compiler hooks. Removed from the virtual browser module. */
   mdx?: MdxConfig;
 }
@@ -211,6 +218,11 @@ export interface StandalonePageItem {
   page: string;
   /** Page title used in the document head. Frontmatter title wins. */
   title?: string;
+  /**
+   * Navigation language this page belongs to, e.g. "ja". Sets the document
+   * language, header navigation, and language selector for the page.
+   */
+  language?: string;
 }
 
 /** Normalized standalone page. */
@@ -221,6 +233,13 @@ export interface StandalonePage {
   filePath: string;
   /** Config-level head-title override. */
   title?: string;
+  /** Navigation language the page belongs to; untagged pages use the default language. */
+  language?: string;
+  /**
+   * Language-independent identity: the file slug without its language folder,
+   * so "ja/home" (language "ja") and "home" are the same page in two languages.
+   */
+  key: string;
 }
 
 export interface SeoConfig {
@@ -402,11 +421,38 @@ export interface DocsConfig {
   api?: ApiConfig;
 }
 
+export type ApiPlaygroundDisplay = 'interactive' | 'simple' | 'none';
+
+export interface ApiPlaygroundConfig {
+  /**
+   * "interactive" (default) renders the "Try it" panel on endpoint pages;
+   * "simple" and "none" show the reference without it.
+   */
+  display?: ApiPlaygroundDisplay;
+  /**
+   * URL of a CORS proxy the playground sends requests through. `$url` in the
+   * value is replaced with the encoded target URL; without it the target URL
+   * is appended. Requests go directly to the API when omitted.
+   */
+  proxy?: string;
+}
+
 export interface ApiConfig {
-  /** Path to a local OpenAPI 3.x spec (JSON or YAML), relative to the project root. */
-  spec: string;
+  /**
+   * One OpenAPI 3.x spec (JSON or YAML) or a list of them: paths relative to
+   * the project root, or https URLs fetched at build time.
+   */
+  spec: string | string[];
   /** Folder inside the content directory for generated endpoint pages. Default "api-reference". */
   directory?: string;
+  /** "Try it" panel settings for endpoint pages. */
+  playground?: ApiPlaygroundConfig;
+}
+
+/** Playground settings after defaults, as carried on the site model. */
+export interface ResolvedApiPlayground {
+  display: ApiPlaygroundDisplay;
+  proxy?: string;
 }
 
 /* ---------------------------------------------------------------------------
@@ -550,37 +596,6 @@ export interface NormalizedFooter {
   attribution: boolean;
 }
 
-export interface ThemeLabels {
-  menu: string;
-  documentationNavigation: string;
-  sections: string;
-  tableOfContents: string;
-  tableOfContentsNavigation: string;
-  searchTitle: string;
-  searching: string;
-  searchUnavailable: string;
-  noResults: string;
-  lastUpdated: string;
-  relatedTopics: string;
-  previousPage: string;
-  nextPage: string;
-  notFound: string;
-  dismissBanner: string;
-  toggleTheme: string;
-  moreOptions: string;
-  copied: string;
-  expand: string;
-  collapse: string;
-  copyPage: string;
-  copyPageDescription: string;
-  viewMarkdown: string;
-  viewMarkdownDescription: string;
-  openInChatGPT: string;
-  openInClaude: string;
-  openInPerplexity: string;
-  askQuestionsAboutPage: string;
-}
-
 export interface SiteModel {
   name?: string;
   logo: {
@@ -607,6 +622,7 @@ export interface SiteModel {
   drilldown?: boolean;
   locale: string;
   labels: ThemeLabels;
+  api: { playground: ResolvedApiPlayground };
   docs: NormalizedDocsConfig;
 }
 
@@ -647,8 +663,16 @@ 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}". */
+  /**
+   * Binds the page to an API operation, e.g. "GET /users/{id}", a webhook
+   * ("webhook userCreated"), or a spec-qualified key on multi-spec sites
+   * ("users.yaml GET /users").
+   */
   openapi?: string;
+  /** Binds the page to a named component schema, e.g. "User" or "users.yaml User". */
+  'openapi-schema'?: string;
+  /** Overrides `api.playground.display` for this page. */
+  playground?: ApiPlaygroundDisplay;
   [key: string]: unknown;
 }
 
@@ -671,9 +695,32 @@ export interface SchemaNode {
   description?: string;
   default?: string;
   enum?: string[];
+  /** Example value (stringified) for parameters, used by samples and the playground. */
+  example?: string;
   children?: SchemaNode[];
 }
 
+/** A security scheme an operation accepts, resolved from components.securitySchemes. */
+export interface SecurityScheme {
+  /** Scheme key in the spec, e.g. "bearerAuth". */
+  name: string;
+  type: 'http' | 'apiKey' | 'oauth2' | 'openIdConnect' | 'unknown';
+  /** HTTP authentication scheme, lowercased: "bearer", "basic", ... */
+  scheme?: string;
+  /** Where an API key is sent. */
+  in?: 'header' | 'query' | 'cookie';
+  /** Header, query, or cookie name carrying an API key. */
+  paramName?: string;
+  description?: string;
+  /** Display label, e.g. "bearerAuth (http bearer)". */
+  label: string;
+}
+
+export interface ApiServer {
+  url: string;
+  description?: string;
+}
+
 export interface OpenApiSample {
   language: string;
   label: string;
@@ -694,9 +741,18 @@ export interface OpenApiResponse {
 
 export interface NormalizedOperation {
   id: string;
-  /** Frontmatter lookup key, e.g. "GET /users/{id}". */
+  /** Frontmatter lookup key, e.g. "GET /users/{id}" or "WEBHOOK userCreated". */
   key: string;
+  /** The configured spec (path or URL) this operation came from. */
+  spec?: string;
+  /** True for OpenAPI `webhooks` entries: payloads the API sends to subscribers. */
+  webhook?: boolean;
+  /** Content folder of the endpoint page, relative to the content directory. */
+  directory?: string;
+  /** Navigation page reference of the endpoint page, e.g. "api-reference/get-user". */
+  pageRef?: string;
   method: string;
+  /** URL path, or the webhook name for webhooks. */
   path: string;
   summary?: string;
   description?: string;
@@ -716,7 +772,23 @@ export interface NormalizedOperation {
     exampleHtml?: string;
   };
   responses: OpenApiResponse[];
-  security: string[];
+  security: SecurityScheme[];
+  /** Servers the operation can be sent to, most specific level first. */
+  servers: ApiServer[];
+  /** URL of the first server; kept for consumers that need a single origin. */
   serverUrl: string;
   samples: OpenApiSample[];
 }
+
+/** A named component schema rendered by an `openapi-schema:` page. */
+export interface SchemaPage {
+  name: string;
+  /** Frontmatter lookup key: the schema name. */
+  key: string;
+  spec?: string;
+  title?: string;
+  description?: string;
+  schema: SchemaNode;
+  example?: string;
+  exampleHtml?: string;
+}

package/types/config.d.ts

@@ -1,3 +1,7 @@
+import type { Translations } from './labels';
+
+export type { ThemeLabels, Translations } from './labels';
+
 import type { PluggableList } from 'unified';
 
 /** Build-time Markdown and MDX compiler extensions. */
@@ -16,8 +20,10 @@ export interface ShisoConfig {
   contentDir?: string;
   /** Absolute site origin (e.g. "https://docs.example.com") used for canonical URLs, og:url, and the sitemap. */
   siteUrl?: string;
-  /** Locale used for deterministic date formatting. Default "en-US". */
+  /** Default locale for UI labels and date formatting. Default "en-US". */
   locale?: string;
+  /** Partial UI label overrides keyed by BCP 47 locale. */
+  translations?: Translations;
   /** Build-time remark and rehype plugins for Markdown and MDX content. */
   mdx?: MdxConfig;
 }

package/types/labels.d.ts

@@ -0,0 +1,101 @@
+export interface ThemeLabels {
+  menu: string;
+  documentationNavigation: string;
+  sections: string;
+  tableOfContents: string;
+  tableOfContentsNavigation: string;
+  searchTitle: string;
+  searching: string;
+  searchUnavailable: string;
+  noResults: string;
+  lastUpdated: string;
+  relatedTopics: string;
+  previousPage: string;
+  nextPage: string;
+  notFound: string;
+  dismissBanner: string;
+  toggleTheme: string;
+  moreOptions: string;
+  copied: string;
+  expand: string;
+  collapse: string;
+  copyPage: string;
+  copyPageDescription: string;
+  viewMarkdown: string;
+  viewMarkdownDescription: string;
+  openInChatGPT: string;
+  openInClaude: string;
+  openInPerplexity: string;
+  askQuestionsAboutPage: string;
+  searchPlaceholder: string;
+  poweredBy: string;
+  copyCode: string;
+  editPage: string;
+  feedbackPrompt: string;
+  feedbackYes: string;
+  feedbackNo: string;
+  feedbackSuccess: string;
+  feedbackError: string;
+  close: string;
+  filterUpdates: string;
+  clear: string;
+  noUpdates: string;
+  codeSnippets: string;
+  contentTabs: string;
+  fileTree: string;
+  diagram: string;
+  diagramError: string;
+  zoomOut: string;
+  resetView: string;
+  zoomIn: string;
+  viewImage: string;
+  viewNamedImage: string;
+  fullSizeImage: string;
+  diagramSource: string;
+  fieldName: string;
+  fieldType: string;
+  fieldDescription: string;
+  fieldRequired: string;
+  fieldDeprecated: string;
+  fieldDefault: string;
+  fieldOptions: string;
+  allowedTypes: string;
+  properties: string;
+  apiHeaders: string;
+  apiPathParameters: string;
+  apiQueryParameters: string;
+  apiCookieParameters: string;
+  apiRequestBody: string;
+  apiResponses: string;
+  apiCodeSamples: string;
+  apiExampleRequest: string;
+  apiExampleResponse: string;
+  apiCredentials: string;
+  apiPlayground: string;
+  apiServer: string;
+  apiAuthorization: string;
+  apiUsername: string;
+  apiPassword: string;
+  apiToken: string;
+  apiApiKey: string;
+  apiBody: string;
+  apiSend: string;
+  apiSending: string;
+  apiCancel: string;
+  apiRequest: string;
+  apiResponse: string;
+  apiResponseHeaders: string;
+  apiResponseBody: string;
+  apiNoResponse: string;
+  apiRequestFailed: string;
+  apiRequestTimedOut: string;
+  apiCookiesUnsupported: string;
+  apiOptional: string;
+  apiElapsed: string;
+  apiCredentialsStored: string;
+  apiPayload: string;
+  apiSchemaProperties: string;
+  apiExample: string;
+}
+
+export type Translations = Record<string, Partial<ThemeLabels>>;

package/vite.config.ts

@@ -41,7 +41,7 @@ function shisoIconRegistry(getDocsConfig: () => DocsConfig, root: string, output
  */
 function shisoOpenApi(
   getDocsConfig: () => DocsConfig,
-  getSpecPath: () => string | undefined,
+  getSpecPaths: () => string[],
   root: string,
   output: string,
 ): Plugin {
@@ -59,8 +59,7 @@ function shisoOpenApi(
       await generate();
     },
     async handleHotUpdate({ file }) {
-      const specPath = getSpecPath();
-      if ((specPath && path.resolve(file) === specPath) || file.endsWith('docs.json')) {
+      if (getSpecPaths().includes(path.resolve(file)) || file.endsWith('docs.json')) {
         await generate();
       }
     },
@@ -494,7 +493,7 @@ export default defineConfig(async () => {
       ),
       shisoOpenApi(
         getDocsConfig,
-        () => configModule.getSpecPath?.(),
+        () => configModule.getSpecPaths?.() ?? [],
         projectRoot,
         path.join(generatedRoot, 'openapi.generated.ts'),
       ),

package/CHANGELOG.md

@@ -1,8 +0,0 @@
-# Changelog
-
-## 1.15.0 - 2026-09-06
-
-### Fixed
-
-- Generate kebab-case OpenAPI documentation filenames and navigation URLs from
-  operation IDs, so `getPixelShares` produces `get-pixel-shares`.