zudoku 0.89.0 → 0.90.0

package/dist/declarations/lib/plugins/openapi/util/seoExtension.d.ts

@@ -0,0 +1,7 @@
+import type { RecordAny } from "../../../util/types.js";
+export declare const SEO_EXTENSION = "x-zudoku-seo";
+export type SeoExtension = {
+    title?: string;
+    description?: string;
+};
+export declare const readSeoExtension: (extensions: RecordAny | null | undefined) => SeoExtension;

package/docs/configuration/api-reference.md

@@ -422,6 +422,8 @@ Extensions that can be applied to tag categories:
 
 - `x-zudoku-collapsed`: Control initial collapsed state of a tag category (default: `true`)
 - `x-zudoku-collapsible`: Control if a tag category can be collapsed (default: `true`)
+- `x-zudoku-seo`: Set the page title and meta description of a tag's page without changing its
+  sidebar label or heading. See [`x-zudoku-seo`](../openapi-extensions/x-zudoku-seo)
 
 Example:
 

package/docs/openapi-extensions/x-display-name.md

@@ -29,3 +29,8 @@ tags:
 
 Without `x-displayName`, the sidebar would show `ai-ops` and `user-mgmt`. With it, the sidebar
 displays `AI Operations` and `User Management` instead.
+
+## Related
+
+- [`x-zudoku-seo`](./x-zudoku-seo) — set a different browser title and meta description for the
+  tag's page

package/docs/openapi-extensions/x-zudoku-seo.md

@@ -0,0 +1,43 @@
+---
+title: x-zudoku-seo
+sidebar_icon: search
+---
+
+Use `x-zudoku-seo` to set the browser title and meta description of a tag's page without changing
+the label shown in the sidebar or the page heading. This is useful when several tags share the same
+[`x-displayName`](./x-display-name) but should still have unique titles for search engines.
+
+## Location
+
+The extension is added at the **Tag Object** level.
+
+| Option        | Type     | Description                                                                   |
+| ------------- | -------- | ----------------------------------------------------------------------------- |
+| `title`       | `string` | Page title used in the `<title>` tag. Replaces `<tag name> - <API title>`.    |
+| `description` | `string` | Content of the `<meta name="description">` tag. Replaces the tag description. |
+
+Both properties are optional. Anything not set falls back to the default behavior. If
+[`metadata.title`](/docs/configuration/overview#metadata) is a template string (e.g.
+`%s - My Company`), it is still applied to the title.
+
+The title and description are rendered on the server, so they are part of the prerendered HTML and
+visible to crawlers without running JavaScript.
+
+## Example
+
+```yaml
+tags:
+  - name: location-key-daily
+    x-displayName: Location Key
+    x-zudoku-seo:
+      title: Daily Forecasts by Location Key - Core Weather
+      description: Daily forecasts for a location key, up to 15 days ahead.
+  - name: location-key-hourly
+    x-displayName: Location Key
+    x-zudoku-seo:
+      title: Hourly Forecasts by Location Key - Core Weather
+      description: Hourly forecasts for a location key, up to 240 hours ahead.
+```
+
+Both tags show `Location Key` in the sidebar and as the page heading, but each page has its own
+browser title and description.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zudoku",
-  "version": "0.89.0",
+  "version": "0.90.0",
   "type": "module",
   "engines": {
     "node": ">=22.22.0"

package/src/lib/plugins/openapi/OperationList.tsx

@@ -15,6 +15,7 @@ import { UNTAGGED_PATH } from "./index.js";
 import { OperationListItem } from "./OperationListItem.js";
 import { useSelectedServer } from "./state.js";
 import { sanitizeMarkdownForMetatag } from "./util/sanitizeMarkdownForMetatag.js";
+import { readSeoExtension } from "./util/seoExtension.js";
 import { useWarmupSchema } from "./util/useWarmupSchema.js";
 
 export const OperationsFragment = graphql(/* GraphQL */ `
@@ -242,6 +243,7 @@ export const OperationList = ({
   }
 
   const { operations, next, prev, description: tagDescription } = schema.tag;
+  const seo = readSeoExtension(schema.tag.extensions);
 
   // Simple heuristic to determine if we should lazy highlight the code
   // This is to avoid the performance issues when there are a lot of operations
@@ -250,13 +252,15 @@ export const OperationList = ({
   // The summary property is preferable here as it is a short description of
   // the API, whereas the description property is typically longer and supports
   // commonmark formatting, making it ill-suited for use in the meta description
-  const metaDescription = tagDescription
-    ? sanitizeMarkdownForMetatag(tagDescription)
-    : summary
-      ? summary
-      : description
-        ? sanitizeMarkdownForMetatag(description)
-        : undefined;
+  const metaDescription =
+    seo.description ??
+    (tagDescription
+      ? sanitizeMarkdownForMetatag(tagDescription)
+      : summary
+        ? summary
+        : description
+          ? sanitizeMarkdownForMetatag(description)
+          : undefined);
 
   const paginationProps = {
     prev: prev
@@ -284,7 +288,10 @@ export const OperationList = ({
     ? "Other endpoints"
     : (schema.tag.extensions?.["x-displayName"] ?? schema.tag.name);
 
-  const helmetTitle = [tagTitle, title].filter(Boolean).join(" - ");
+  // `x-zudoku-seo` only affects the document head, the sidebar and heading
+  // keep using `x-displayName`
+  const helmetTitle =
+    seo.title ?? [tagTitle, title].filter(Boolean).join(" - ");
 
   return (
     <div

package/src/lib/plugins/openapi/util/seoExtension.ts

@@ -0,0 +1,30 @@
+import type { RecordAny } from "../../../util/types.js";
+
+/** Overrides a page's `<title>` and meta description. See the `x-zudoku-seo` docs. */
+export const SEO_EXTENSION = "x-zudoku-seo";
+
+export type SeoExtension = {
+  title?: string;
+  description?: string;
+};
+
+const nonEmptyString = (value: unknown) =>
+  typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+
+/**
+ * Reads `x-zudoku-seo` off an object's extensions. `extensions` reaches the
+ * client as untyped JSON, so anything other than a non-empty string is ignored
+ * and the page falls back to its default title and description.
+ */
+export const readSeoExtension = (
+  extensions: RecordAny | null | undefined,
+): SeoExtension => {
+  const seo: unknown = extensions?.[SEO_EXTENSION];
+  if (typeof seo !== "object" || seo === null) return {};
+
+  return {
+    title: "title" in seo ? nonEmptyString(seo.title) : undefined,
+    description:
+      "description" in seo ? nonEmptyString(seo.description) : undefined,
+  };
+};