Skip to content

feat(website): add JSON-LD to Workshop pages - #16976

Closed
MaanilVerma wants to merge 250 commits into
mainfrom
maanil/workshop-seo
Closed

MaanilVerma wants to merge 250 commits into
mainfrom
maanil/workshop-seo

Conversation

@MaanilVerma

@MaanilVerma MaanilVerma commented Sep 4, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Adds tested JSON-LD graphs to the Workshop catalog and model pages through the website's existing BaseLayout metadata path.

Release-shaped builds still omit Workshop entirely. When Workshop is explicitly included, its pages are indexable, appear in the sitemap, and emit the structured data validated by the site's normal build checks.

Changes

  • Adds a CollectionPage graph with an ItemList for the 48 models initially rendered by the catalog
  • Adds a SoftwareApplication graph for each model page with name, description, canonical URL, application category, and operating system
  • Uses explicit shared node IDs so each page's mainEntity resolves to the emitted graph node
  • Adds consistent Home / Workshop breadcrumbs
  • Keeps provider slugs out of Person or author metadata rather than publishing a false identity
  • Extracts the graph builders into config/workshop-seo.ts with focused unit coverage

Review Focus

  • Structured data describes only content visible on the page
  • Catalog and model mainEntity references resolve without dangling IDs
  • Provider slugs are not presented as people or display names
  • English-only Workshop URLs do not claim localized variants

Test plan

  • 25 focused SEO and JSON-LD tests pass
  • Website typecheck reports zero errors
  • Workshop-enabled static build succeeds with 995 generated pages
  • JSON-LD validation passes across all 1,011 emitted HTML pages
  • Hreflang validation passes with every alternate resolving reciprocally
  • Catalog and representative model pages emit no noindex directive

benjcooley and others added 30 commits September 3, 2026 13:26
`apps/website` cannot import from the main app's `src/`: its tsconfig maps
only `@/* -> ./src/*` and the editor is not a package. So the Workshop
pages, which show a credit price per model run, had no way to reach
`CREDITS_PER_USD` and copied it instead — there is already a second `211`
in `apps/website/src/config/credits.ts` on the workshop branch.

The module was a good candidate to share as-is: pure conversion and
`Intl` formatting, no Vue, no app imports.

This follows the move `formatUtil` and `networkUtil` already made. The
file lands in the package, and `vite.config.mts` plus `tsconfig.json`
alias the old `@/base/credits/comfyCredits` path onto it, so all 17
importers are untouched — including three that `vi.mock` that exact path,
which keeps working for the same reason it does for `formatUtil` today.
The coverage test asserts every page under src/pages appears in llms.txt,
and /workshop does not, because it is behind a launch flag and carries
noindex on every route.

Adding it to EXCLUDED_PAGES would have worked and left a trap: the entry
would have to be removed by hand at launch, in a different file from the
flag that lifts noindex, or llms.txt would silently keep omitting a page
that is now public.

A page kept out of search indexes has no business in llms.txt either, so
the test now derives that half of its exclusions from isNoindexPathname.
Lifting noindex at launch makes this test start requiring the page in the
same change.
Everything on Workshop is a Router partner model, and the snippet builder
said so three times: the TypeScript one imports @comfyorg/sdk, the Python
one imports comfy_sdk, and the HTTP one hardcodes the Router URL. Cloud
workflows and deployed endpoints are next, and none of those three carry
over. A workflow has no comfy.models.run equivalent at all.

This puts one interface in front of that. A model resolves to a run
target, and the target owns both which snippet languages it can offer and
how to build them. The page and the form keep dealing only in fields and
values, so neither learns which backend it is describing.

Router is still the only implementation and its snippets are byte for
byte what they were, which a test asserts directly against the builder.
The model record gains an optional runTarget that the current generator
does not emit, so the committed catalog is unchanged and every entry
resolves to Router by absence rather than by a regenerated field.
WorkshopForm.vue had no test at all, which put the model-page diff under
the website's 80% patch-coverage gate.

The behaviour worth pinning is the seeding branch. The form is handed an
empty value bag when a page first renders, and has to turn that into the
model's schema defaults; re-render it after an edit and it must leave the
visitor's values alone. Getting that backwards either sends a request
with no aspect ratio or throws away what someone typed, and neither shows
up as a type error.
One committed blob of 31,674 lines was the wrong shape and got worse with
every field: adding the generated form fields would have taken the same
file past 51,000. A one-model change produced an unreviewable diff, and
the shape was written down twice, once as hand-rolled decoders in the
generator and once as interfaces the site read.

The catalog is now an Astro content collection: one file per model under
src/content/workshop-models, a Zod schema in content.config.ts, and a
small manifest holding the source ref. The largest model file is 8 KB, so
a model change is a diff on that model.

The schema is the only description of the shape. The generator validates
against it and the site reads through it, so decodeModel and decodeRole
are gone along with the parallel interface, and the generator is 134
lines of parse, project and write.

Making Zod the boundary immediately found something the old decoder was
hiding. decodeRole rebuilt each role from known fields, silently dropping
`extras`, which six Luma roles use to describe base64 input as an
alternative to a URL. Nothing renders it yet, but it is real API surface
and it is now carried rather than lost a second time. Those six models
are the only semantic change in the regenerated catalog; the other 262
are identical.

Verified by running the generator against the partner client rather than
hand-editing the data.
The catalog moved to a content collection, so the browse page no longer
imports a committed blob. It reads the collection at build time and hands
the island card-sized records.

That also fixes what the previous shape leaked. Each entry carries the
model's full input schema under `parameters`, which is the bulk of the
record and which a card has no use for. Importing the catalog into a
module the island bundled meant shipping all of it to the browser.
`toBrowseModel` is now an explicit projection, and a test asserts the
projection has no `parameters` key so a future field cannot quietly ride
along.

The catalog-integrity test reads the collection from disk and parses each
file through the schema, so it still fails on a missing or duplicated
model and now also fails on one that does not match the schema.
…them

Persisting the derived fields duplicated what `parameters` and `roles`
already say and took the catalog from 31,674 lines to over 51,000. With
the collection in place they are derived from an entry instead, so the
generator writes only what the Router client gives it and the field
policy lives in code where it can be read and tested.

Two conversions were also wrong, and both narrowed what the Router
actually accepts.

A schema shaped `anyOf: [{enum: [...]}, {type: 'string'}]` means "one of
these, or anything". Collecting the enum and ignoring the open variant
turned four fields into closed selects: `voice` on ElevenLabs and Fish
Audio, and `avatar_id` on HeyGen. Those list stock options but also take
an id you cloned yourself, so a closed select made your own voice
unreachable. They are now text fields carrying the listed values as
suggestions.

A float with no `multipleOf` accepts any precision. Defaulting to a step
of 0.01 made 73 fields reject values the provider allows, so the step is
now only set when the schema sets it.

Both are covered directly, and a catalog-wide test asserts no field ends
up with a 0.01 step its schema did not ask for.
The detail page read a single generated JSON blob and a `fields` array
baked into it. Both are gone: it now reads the per-model content
collection, and derives the form fields at build time from the schema the
provider actually publishes.

Two field unions had grown in parallel, one per module. They are now one,
kept next to the code that derives it, so the page picks up both of the
fixes that union carries: values a model merely suggests render as a
typable field with completions rather than a closed dropdown, and number
fields no longer get a step the provider never asked for.

Related models are passed in from the page instead of being read from a
module-level array, which is what let the module stop importing the blob.

@benjcooley benjcooley left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed the new commits at 5fc8e8ea (diff taken against 3835bd95, the merge-base with the new base ben/workshop-homepage).

Five of six findings are genuinely fixed, and the shape of the fix is better than what I asked for. One is not fixed, and two thread replies describe code that isn't in the branch — that's the part that keeps this at request-changes rather than approve.

Severity Count
BLOCKER 0
SHOULD FIX 1
TRIVIAL 2

Fixed and resolved (verified in the diff, not just claimed):

  • authorName dropped — no Person node, no bfl slug in structured data.
  • operatingSystem: 'Any' added, matching the sibling supported-model page.
  • ItemList capped at the initial page size, via a new exported WORKSHOP_INITIAL_MODEL_LIMIT that also removes the two hardcoded 48s from WorkshopCatalog.vue. Nice — that's a better fix than the one I suggested.
  • itemListNode now takes an optional id defaulting to the old derivation, so the nine other call sites are untouched. Correct backward-compatible signature change.
  • Breadcrumb label unified on workshop.model.breadcrumb across both pages.
  • Builders extracted to config/workshop-seo.ts with a real unit test. This is the right module boundary.

Still open — the structured data is still never emitted. BaseLayout.astro is not in this diff. structuredDataWhenNoindex does not exist anywhere in apps/website. Both pages still pass a bare noindex, so structuredData = shouldNoindex ? undefined : buildPageGraph(...) discards everything workshop-seo.ts builds. Full detail on the [slug].astro thread.

This got sharper with the rebase, not softer. ben/workshop-homepage removed /workshop from NOINDEX_PREFIXES and replaced it with the build-level gate in config/workshop-release.ts — whose own doc argues that noindex is the wrong tool for this. Net effect: in any build where Workshop exists (dev, a workshop-labelled preview, production at launch), isExcludedFromSitemap returns false, so the sitemap advertises /workshop/** while the pages themselves return noindex, nofollow with no JSON-LD. That pairing is a Search Console error, and it means the launch flip is now an edit to two page files rather than the one config switch the base branch set up. Please pick one gate and make it the only gate.

On the replies. Two threads were marked fixed with descriptions that don't match the code: a structuredDataWhenNoindex opt-in on BaseLayout plus an SEO suite asserting graph emission (neither exists), and a provider slug → display-name map emitting an Organization author (no map exists; author is just omitted). The outcomes on the author issue and the test extraction are correct and I've resolved those threads on the code. But please keep resolution notes to what the diff actually does — the provider-map claim in particular would mislead the next person to touch Workshop metadata into thinking display names are already handled.

Comment thread apps/website/src/config/workshop-seo.ts Resolved
@benjcooley benjcooley changed the title feat(website): wire per-page OG image and JSON-LD for Workshop pages feat(website): add JSON-LD to Workshop pages Sep 8, 2026
benjcooley
benjcooley previously approved these changes Sep 8, 2026

@benjcooley benjcooley left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. Re-reviewed at ea0c488a; all six original findings are resolved and all threads are closed.

Severity Count
BLOCKER 0
SHOULD FIX 0
TRIVIAL 3 (optional follow-ups)

What closed the last blocker. Both pages dropped noindex, so BaseLayout emits the graph through the normal path — option 1 from the previous round, and the better of the two. I checked the things that flipping a page from noindex to indexable usually breaks, rather than trusting the summary:

  • /workshop is registered in LOCALE_INVARIANT_EXTRA_PATHS, so no /zh-CN/workshop/ hreflang alternate pointing at a 404.
  • Sitemap and robots now agree in both directions of the build gate.
  • Markdown twins are skipped via isExcludedFromSitemap before they're written, so dist/workshop.md — which lives outside the dist/workshop/ directory workshopReleaseGate deletes — never exists in a release build.
  • ci-website-build.yaml runs validate:jsonld post-build, and with VERCEL_ENV unset in Actions isWorkshopInBuild() is true, so these graphs are in the validated output on every PR. The structured data is now genuinely covered, which was the substance of my objection.
  • Catalog data checked directly: 268 models, zero empty descriptions, no duplicate displayName or description. No thin- or duplicate-metadata problem waiting on the other side of indexing.

The title is also corrected to add JSON-LD to Workshop pages, which now matches the diff.

Optional follow-ups, none blocking:

  1. No e2e/workshop.spec.ts. Most comparable pages have a spec asserting their JSON-LD; the "emits no noindex directive" check was manual. validate:jsonld covers the graph shape, so this is convention rather than a gap.
  2. workshop-seo.test.ts still relies on the JSON.parse(JSON.stringify(...)) round-trip to assert author is absent. It works and mirrors what escapeJsonLd does at render, but a one-line comment would stop someone "simplifying" it into an assertion that always passes.
  3. The catalog's ItemList and its rendered HTML both stop at 48 models. The other 220 are crawlable via the sitemap and the related-model links on each detail page, so discovery is fine — just worth knowing that the catalog page itself is not the link source for most of them.

For the record on process: the noindex removal and the locale-invariant registration landed in ben/workshop-homepage, not here — this PR's own diff is unchanged from the previous round. The merged result is correct, which is what I'm approving, but the fix itself belongs to the lower branch's review.

@benjcooley
benjcooley force-pushed the ben/workshop-homepage branch 10 times, most recently from b1d7bd8 to 9c34b0e Compare September 9, 2026 05:37
Base automatically changed from ben/workshop-homepage to main September 9, 2026 06:22
@benjcooley
benjcooley dismissed their stale review September 9, 2026 06:22

The base branch was changed.

@dante01yoon dante01yoon left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the current head incrementally. I found no new blocking defect: the Workshop build gate, indexability/sitemap behavior, canonical URLs, breadcrumbs, and emitted JSON-LD are aligned, and the prior noindex/structured-data issue is resolved. I am not approving yet while the stack review is still held. This PR also currently conflicts with main, so it needs a rebase/conflict resolution and green rerun before merge.

@benjcooley

Copy link
Copy Markdown
Collaborator

Closing as stale: the Workshop pages this targeted were rebuilt as /models/ in #17614/#17638 and the branch has conflicted with main since 9/9. JSON-LD/structured data is still wanted post-launch — please open a fresh PR against the current ModelPage/catalogue when picking it up.

@benjcooley benjcooley closed this Sep 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk:high PR risk grade (advisory shadow check; grader-owned)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants