Support page.title and page.description

package.json

@@ -40,7 +40,8 @@
     "execa": "^9.3.1",
     "jstransformer-handlebars": "^1.2.0",
     "metalsmith": "^2.6.3",
-    "prettier": "^3.0.0"
+    "prettier": "^3.0.0",
+    "zod": "^3.23.8"
   },
   "devDependencies": {
     "@types/command-exists": "^1.2.3",

src/data/paths.yaml

@@ -1,3 +1,20 @@
 ---
 /acs/systems:
-  description: Access Control Systems
+  page:
+    title: Systems
+    description: Access Control Systems
+
+/acs/systems/get:
+  page:
+    title: Get an ACS System
+    description: Get an ACS System
+
+/acs/systems/list:
+  page:
+    title: List ACS Systems
+    description: List ACS Systems
+
+/acs/systems/list_compatible_credential_manager_acs_systems:
+  page:
+    title: List Compatible Credential Manager ACS Systems
+    description: List Compatible Credential Manager ACS Systems

src/layouts/api-endpoint.hbs

@@ -1,3 +1,6 @@
+---
+description: {{page.description}}
+---
 # {{title}}
 
 ```

src/layouts/api-route.hbs

@@ -1,5 +1,5 @@
 ---
-description: {{description}}
+description: {{page.description}}
 ---
 {{#each resources}}
 # `{{name}}`

src/lib/blueprint.ts

@@ -1,6 +1,7 @@
 import { createBlueprint, TypesModuleSchema } from '@seamapi/blueprint'
 import * as types from '@seamapi/types/connect'
 import type Metalsmith from 'metalsmith'
+import { z } from 'zod'
 
 import { formatCode } from './format-code.js'
 
@@ -14,7 +15,10 @@ export const blueprint = async (
     'codeSampleDefinitions' in metadata ? metadata.codeSampleDefinitions : []
 
   // UPSTREAM: Ideally, path metadata would be unnecessary and contained inside the blueprint.
-  const pathMetadata = 'pathMetadata' in metadata ? metadata.pathMetadata : {}
+  const pathMetadata =
+    'pathMetadata' in metadata
+      ? PathMetadataSchema.parse(metadata.pathMetadata)
+      : {}
 
   const typesModule = TypesModuleSchema.parse({
     ...types,
@@ -24,3 +28,15 @@ export const blueprint = async (
   const blueprint = await createBlueprint(typesModule, { formatCode })
   Object.assign(metadata, { ...blueprint, pathMetadata })
 }
+
+const PathMetadataSchema = z.record(
+  z.string(),
+  z.object({
+    page: z.object({
+      title: z.string().trim().min(1),
+      description: z.string().trim().min(1),
+    }),
+  }),
+)
+
+export type PathMetadata = z.infer<typeof PathMetadataSchema>

src/lib/layout-context.ts

@@ -7,7 +7,7 @@ import type {
 } from '@seamapi/blueprint'
 import { pascalCase } from 'change-case'
 
-import type { PathMetadata } from './reference.js'
+import type { PathMetadata } from './blueprint.js'
 
 const supportedSdks: CodeSampleSdk[] = [
   'javascript',
@@ -21,6 +21,10 @@ export interface EndpointLayoutContext {
   description: string
   title: string
   path: string
+  page: {
+    title: string
+    description: string
+  }
   request: {
     preferredMethod: string
     parameters: Array<{
@@ -54,10 +58,16 @@ export interface EndpointLayoutContext {
 export function setEndpointLayoutContext(
   file: Partial<EndpointLayoutContext>,
   endpoint: Endpoint,
+  pathMetadata: PathMetadata,
 ): void {
   file.description = endpoint.description
   file.title = endpoint.title
   file.path = endpoint.path
+  const page = pathMetadata[endpoint.path]?.page
+  if (page == null) {
+    throw new Error(`Missing page metadata for ${endpoint.path}`)
+  }
+  file.page = page
 
   file.request = {
     preferredMethod: endpoint.request?.preferredMethod ?? '',
@@ -115,6 +125,10 @@ interface ContextResource {
 type ContextEndpoint = Pick<Endpoint, 'path' | 'description'>
 
 export interface RouteLayoutContext {
+  page: {
+    title: string
+    description: string
+  }
   description: string
   resources: ContextResource[]
   endpoints: ContextEndpoint[]
@@ -126,12 +140,11 @@ export function setApiRouteLayoutContext(
   blueprint: Blueprint,
   pathMetadata: PathMetadata,
 ): void {
-  const description = pathMetadata[route.path]?.description
-  if (description == null || description.trim() === '') {
-    throw new Error(`Missing description for ${route.path}`)
+  const page = pathMetadata[route.path]?.page
+  if (page == null) {
+    throw new Error(`Missing page metadata for ${route.path}`)
   }
-
-  file.description = description
+  file.page = page
   file.endpoints = route.endpoints.map(({ path, name, description }) => ({
     path,
     name,

src/lib/reference.ts

@@ -1,6 +1,7 @@
 import type { Blueprint } from '@seamapi/blueprint'
 import type Metalsmith from 'metalsmith'
 
+import type { PathMetadata } from './blueprint.js'
 import {
   type EndpointLayoutContext,
   type RouteLayoutContext,
@@ -14,13 +15,6 @@ type Metadata = Partial<Pick<Blueprint, 'routes' | 'resources'>>
 
 type File = EndpointLayoutContext & RouteLayoutContext & { layout: string }
 
-export type PathMetadata = Record<
-  string,
-  {
-    description?: string | null
-  }
->
-
 export const reference = (
   files: Metalsmith.Files,
   metalsmith: Metalsmith,
@@ -59,7 +53,7 @@ export const reference = (
       }
       const file = files[k] as unknown as File
       file.layout = 'api-endpoint.hbs'
-      setEndpointLayoutContext(file, endpoint)
+      setEndpointLayoutContext(file, endpoint, pathMetadata)
 
       for (const sdk of sdks) {
         const k = `sdk/${sdk}${endpoint.path}.md`
@@ -68,7 +62,7 @@ export const reference = (
         }
         const file = files[k] as unknown as File
         file.layout = 'sdk-reference.hbs'
-        setEndpointLayoutContext(file, endpoint)
+        setEndpointLayoutContext(file, endpoint, pathMetadata)
       }
     }
   }