feat: catalog model detail pages with examples, schema tables, and UI by superhighfives · Pull Request #29202 · cloudflare/cloudflare-docs

superhighfives · 2026-03-20T23:06:24Z

Adds fully-featured model detail pages for catalog models (models sourced from an external catalog API rather than the Workers AI registry), with rich UI for examples and parameter schemas.

new CatalogSchemaTable component renders input/output parameter tables (Name / Type / Default / Description) with nested property support, required badges, and array/object suffixes
new ExampleCard component with stack and side-by-side layouts — Usage section stacks vertically, Examples show code + response image side by side; response image is sticky so it stays in view while scrolling tall code blocks
tab bar and "Response 200" label are vertically aligned; 200 status badge uses green monospace styling
code block stretches to fill image height in side-by-side layout; non-active tab panels correctly hidden
[...name].astro branches on dataSource — catalog models use the new components, legacy models fall back to existing SchemaViewer
model-resolver.ts converts catalog model JSON to the shared ResolvedModel type; normalizePricingUnit handles keys without per_ prefix correctly
default_example marked nullable in the Zod schema to match API reality
redirects added for catalog model slugs
bin/fetch-catalog-models.ts script for syncing catalog model JSON locally
three initial catalog model JSON files included as examples

Add infrastructure to auto-generate Workers AI model documentation from the unified catalog API, running alongside the existing legacy system. - New catalog-models content collection with schema matching unified catalog - Fetch script supporting both API fetch and local JSON import - Model resolver that merges catalog and legacy sources (catalog wins) - Updated [name].astro to display catalog-specific content (code snippets, examples) - New CodeSnippets.astro component for rendering code examples - Graceful handling of models without JSON schemas - Fixed author extraction for both @cf/author/model and author/model formats - Split into model-types.ts, model-helpers.ts, model-resolver.ts for server/client boundary

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

@hf

- add [...name].astro page using resolver for both catalog and legacy models - add ExampleCard component with side-by-side code tabs + output image - add 97 redirects for old model slug -> full model ID migration - use full model ID as slug (preserves @cf/@hf prefix) - remove getModelSlug (identity function) - remove dead exports from resolver - fix zod schema: astro/zod import, record key types, code_snippets on examples - fix division by zero, null checks, description whitespace - trim name/description in fetch script - add TODO.md for staging URL and pricing unit edge cases

- rewrite fetch script to list model IDs then fetch individual details - add CF_API_BASE_URL env var for staging/production switching - add concurrency control (5 parallel requests) - fix SchemaRow crash: optional chain on node.annotations and node.validations

…e image, 200 badge

Copilot

Pull request overview

Adds a new “catalog model” data source (local JSON synced from an external catalog API) and updates the Workers AI model listing/detail pages to render richer, catalog-specific UI (examples + schema tables), while keeping legacy models working via a unified ResolvedModel type.

Changes:

Introduces catalog-models content collection + Zod schema, plus resolver utilities to merge catalog + legacy into a unified ResolvedModel[].
Updates /workers-ai/models listing and [...name] detail pages to use resolved models and render new catalog UI (ExampleCard, CatalogSchemaTable).
Adds scripts for syncing/comparing catalog models locally and adds redirects for the new model URL scheme.

Reviewed changes

Copilot reviewed 21 out of 24 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/util/model-types.ts	Adds unified `ResolvedModel` type used across catalog + legacy models
src/util/model-resolver.ts	Resolves/merges catalog + legacy models; normalizes pricing units
src/util/model-helpers.ts	Adds client-safe helper for extracting model author/provider
src/schemas/index.ts	Re-exports new catalog schema module
src/schemas/catalog-models.ts	Adds Zod schema/types for catalog model JSON
src/content.config.ts	Adds `catalog-models` content collection
src/pages/workers-ai/models/index.astro	Switches model list page to use `getResolvedModels()`
src/pages/workers-ai/models/[...name].astro	Adds catalog branching for Usage/Examples/Parameters rendering
src/components/ModelCatalog.tsx	Allows listing to accept `ResolvedModel` and updates model links/authors
src/components/models/ModelInfo.tsx	Updates author derivation to support both ID formats
src/components/models/ModelFeatures.tsx	Allows rendering with `ResolvedModel` union type
src/components/models/ModelBadges.tsx	Allows rendering with `ResolvedModel` union type
src/components/models/SchemaRow.astro	Makes schema annotations/validations access null-safe
src/components/models/SchemaParamName.astro	Adds nested parameter name indentation + array/object suffixes
src/components/models/CatalogSchemaTable.astro	New schema table renderer with nested property flattening
src/components/models/ExampleCard.astro	New example UI with stacked/side-by-side layouts and sticky response image
src/components/models/CodeSnippets.astro	Adds snippet tab renderer (currently not referenced)
src/content/catalog-models/google-nano-banana.json	Adds example catalog model JSON (with examples + schema)
src/content/catalog-models/flux-2-klein-9b.json	Adds example catalog model JSON
src/content/catalog-models/black-forest-labs-flux-2-klein-9b.json	Adds another catalog model JSON (appears duplicative)
src/content/catalog-models/.gitkeep	Ensures directory is tracked
public/__redirects	Adds redirects for legacy model slugs to full model IDs
bin/fetch-catalog-models.ts	Script to sync catalog models from API or file export
bin/compare-model-sources.ts	Script to compare legacy vs catalog coverage/migration progress

Comments suppressed due to low confidence (1)

src/pages/workers-ai/models/[...name].astro:66

The catalog Usage detection only checks firstExample.code_snippets, but ResolvedModel also exposes top-level codeSnippets (from model.code_snippets) and that field is currently unused. If the catalog API returns snippets at the model level (or the first example lacks snippets), the page will render no Usage section even though snippets exist. Consider treating model.codeSnippets as a fallback for hasCatalogUsage and passing it into ExampleCard via fallbackSnippets.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/util/model-types.ts

src/components/models/CodeSnippets.astro

src/components/models/CatalogSchemaTable.astro

src/components/models/ExampleCard.astro

src/content/catalog-models/google-nano-banana.json

src/content/catalog-models/black-forest-labs-flux-2-klein-9b.json

…ncKey, remove dead code and duplicate model

…flux-2-klein-9b

superhighfives and others added 7 commits March 20, 2026 16:05

Fix Nano description

8cbb473

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Fix for normalizing pricing

8261bea

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

catalog model pages: ExampleCard layout, schema table, sticky respons…

7212b22

…e image, 200 badge

Updated data for Google Nano Banana

1a91502

superhighfives requested review from a team and kodster28 as code owners March 20, 2026 23:06

Copilot AI review requested due to automatic review settings March 20, 2026 23:06

github-actions bot added the size/xl label Mar 20, 2026

github-actions bot assigned kodster28 Mar 20, 2026

Copilot started reviewing on behalf of superhighfives March 20, 2026 23:06 View session

Copilot AI reviewed Mar 20, 2026

View reviewed changes

superhighfives added 5 commits March 20, 2026 16:30

fix PR review issues: remove .gitkeep, fix jepg typo, close quote, sy…

2b475d1

…ncKey, remove dead code and duplicate model

restore black-forest-labs-flux-2-klein-9b.json — separate model from …

5ff2d61

…flux-2-klein-9b

add seti:* icons to example tabs, matching workersAiExamples convention

f102451

fix type error: use StarlightIcon type for icon map and getIcon return

0194a8f

fix: remove unused name param from [...name].astro

93b3da1

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: catalog model detail pages with examples, schema tables, and UI#29202

feat: catalog model detail pages with examples, schema tables, and UI#29202
superhighfives wants to merge 12 commits intocloudflare:productionfrom
superhighfives:catalog-models

superhighfives commented Mar 20, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

superhighfives commented Mar 20, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants