feat: add ItemList structured data for comparison table pages

[alexleventer]

Summary

• Adds a new schema collector (comparison-table-entity.html) that parses Markdown feature-comparison tables on /comparisons/ pages and emits JSON-LD ItemList structured data
• Wires the collector into graph-builder.html so it's included in the page's schema graph

Test plan

• Verify make build succeeds
• Spot-check a comparison page (e.g., Pulumi vs Terraform) and confirm the ItemList JSON-LD block appears in the page source
• Confirm non-comparison pages are unaffected

🤖 Generated with Claude Code

[claude]

Docs Review

Scope: Reviewed all changes in this PR — the new layouts/partials/schema/collectors/comparison-table-entity.html (90 lines added) and the integration into layouts/partials/schema/graph-builder.html (8 lines added).

Overall this is a well-structured addition that follows the existing collector patterns (matches video-entity.html integration style, proper Scratch cleanup, correct return pattern). The JSON-LD schema.org types (ItemList, ListItem) are valid. However, there is one significant semantic bug in the title-to-column mapping.

---

Issues

1. Bug — Product/competitor label mismatch on 2 of 7 pages (comparison-table-entity.html:10-18)

The title parsing assumes the order of names in the page title matches the order of columns in the table. This breaks on pages where the title order is reversed relative to the table columns.

Affected pages:

Page	h1 (title)	Table columns	Result
terraform/_index.md	"Terraform vs. Pulumi IaC"	| Pulumi | Terraform |	Labels swapped — Terraform label paired with Pulumi's values
crossplane.md	"Crossplane vs Pulumi"	| Pulumi | Crossplane |	Labels swapped — Crossplane label paired with Pulumi's values

For example, on the Terraform page, the ListItem descriptions would read:
"Terraform: Python, TypeScript, JavaScript, Go, C#, F#, Java, YAML | Pulumi IaC: HashiCorp Configuration Language (HCL)"
...which is backwards.

The other 5 pages with | Feature | tables produce correct output because their title order matches column order.

Suggested fix: Extract column names from the table header row itself rather than parsing the page title. The header row (e.g., | Feature | Pulumi | Terraform |) already contains the product names in the correct column order. This would replace lines 7–18 with something like:

{{/* Extract column names from the table header row */}}
{{ $headerCells := split (index $allTableLines 0) "|" }}
{{ $productName := index $headerCells 2 | strings.TrimSpace }}
{{ $competitorName := index $headerCells 3 | strings.TrimSpace }}

This requires restructuring slightly (moving the header extraction before the name check), but it eliminates the title/column mismatch entirely and is more robust against future title changes.

2. Minor — Trailing " IaC" in competitor name (comparison-table-entity.html:14-17)

On the Terraform page (h1: "Terraform vs. Pulumi IaC"), the fallback title parser produces $competitorName = "Pulumi IaC". This flows into the entity name as "Terraform vs. Pulumi IaC Feature Comparison" and the description as "Side-by-side feature comparison of Terraform and Pulumi IaC for infrastructure as code." The trailing "IaC" is a bit awkward in structured data. This would also be resolved by extracting names from the table header.

---

Looks good

• Graph-builder integration (graph-builder.html:174-180): Follows the exact same guard pattern as video-entity.html. Clean.
• Table parsing logic: The after 2 to skip header/separator, the split ... "|" indexing, separator row detection regex, Markdown link stripping, and HTML tag removal all look correct.
• Scratch usage and cleanup: Properly sets, accumulates, reads, and deletes both compRows and compItems.
• URL scoping: The strings.Contains .RelPermalink "/comparisons/" guard correctly limits this to comparison pages only, and returning an empty dict for non-matches avoids polluting the graph on other pages.
• Schema.org validity: ItemList with ListItem elements is valid structured data. The @id, position, name, and description fields are appropriate.

---

Mention me (@claude) if you'd like additional reviews or want me to help implement the fix.

[pulumi-bot]

Your site preview for commit 18795e9 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-18477-18795e94.s3-website.us-west-2.amazonaws.com

[pulumi-bot]

Lighthouse Performance Report

Commit: 18795e9 | Metric definitions

Page	Device	Score	FCP	LCP	TBT	CLS	SI
Homepage	Mobile	🟡 72	2.4s	2.4s	674ms	0.010	6.6s
Homepage	Desktop	🟢 95	0.8s	1.1s	18ms	0.080	1.1s
Install Pulumi	Mobile	🔴 40	4.5s	5.8s	236ms	0.431	6.9s
Install Pulumi	Desktop	🟡 88	1.0s	1.4s	18ms	0.020	2.6s
AWS Get Started	Mobile	🟡 52	7.4s	9.6s	295ms	0.000	7.4s
AWS Get Started	Desktop	🟡 88	1.0s	1.4s	19ms	0.033	2.6s

[alexleventer]

@claude - review again pls

[claude]

Claude finished @alexleventer's task in 2m 36s —— View job

---

Docs Review

• Read changed files
• Review comparison pages for column/title alignment
• Assess schema correctness
• Post findings

---

Re-reviewed the full diff (comparison-table-entity.html + graph-builder.html). The previous critical bug remains unfixed, and I found two additional issues.

---

Bug 1 (Critical, unchanged) — Product/competitor labels are swapped on 2 of 7 pages

comparison-table-entity.html:10-18

The title-parsing logic assigns $productName / $competitorName from the h1 text, but the table columns are always ordered Pulumi first, competitor second — regardless of how the h1 is worded. On two pages the h1 has the competitor name first, so the labels are assigned backwards:

Page	h1	Table col 2 (val1)	Table col 3 (val2)	Parsed $productName	Parsed $competitorName	Effect
terraform/_index.md	"Terraform vs. Pulumi IaC"	Pulumi data	Terraform data	"Terraform"	"Pulumi IaC"	Description reads "Terraform: Python, TS … | Pulumi IaC: HCL" — backwards
crossplane.md	"Crossplane vs Pulumi"	Pulumi data	Crossplane data	"Crossplane"	"Pulumi"	Description reads "Crossplane: Python, TS … | Pulumi: Kubernetes CRDs" — backwards

The root cause: $productName and $competitorName are derived from the h1 word order, but $val1/$val2 are always fixed at cell index 2 and 3 in the table — the two sources are independent and can disagree.

Suggested fix — extract column names from the table header itself, which is always in the correct order:

{{/* Replace lines 7-18 with: */}}
{{ $allTableLines := findRE `(?m)^\|.+\|` $afterHeader }}

{{ if ge (len $allTableLines) 3 }}
  {{ $headerCells := split (index $allTableLines 0) "|" }}
  {{ $productName   := index $headerCells 2 | strings.TrimSpace }}
  {{ $competitorName := index $headerCells 3 | strings.TrimSpace }}

This ties the label directly to the column position and is immune to h1 wording. Fix this →

---

Bug 2 (Moderate, new) — Verbose competitor name on 2 more pages

comparison-table-entity.html:11-12

For pages where the h1 reads "Pulumi vs. <Long Name>", $competitorName gets the full h1 wording, not the shorter column header name:

Page	h1 (parsed $competitorName)	Table col 3 header
aws-cdk/_index.md	"AWS Cloud Development Kit (CDK)"	"AWS CDK"
cdktf/_index.md	"CDK for Terraform (CDKTF)"	"CDKTF"

The data is attributed to the right product (columns aren't swapped), but the entity name and description fields will use the long form: e.g., "Pulumi vs. CDK for Terraform (CDKTF) Feature Comparison". Using the table column header would produce the shorter, canonical form actually used in the comparison. This too is resolved by the fix above.

---

Issue 3 (Minor, new) — ItemList is not linked from the WebPage node

graph-builder.html:174-180

The ItemList entity is appended to $graph as a standalone node, but the WebPage entity has no outgoing reference to it. Contrast with how mainEntity and breadcrumb are wired:

{{ $webpage = merge $webpage (dict "mainEntity" (dict "@id" "#main-content")) }}

Without an analogous hasPart (or mainEntity) reference from $webpage, the ItemList floats unconnected in the graph. This is valid JSON-LD and Google's Rich Results Test will still parse it, but explicitly connecting it strengthens the semantic relationship and is more consistent with the rest of the collector pattern.

---

Looks good (unchanged)

• Graph-builder integration: follows video-entity.html guard pattern exactly. Clean.
• Table parsing: after 2, separator-row regex, Markdown link stripping, HTML tag removal all correct.
• Scratch usage: proper set/accumulate/read/delete lifecycle on both compRows and compItems.
• URL scoping: strings.Contains .RelPermalink "/comparisons/" guard is correct.
• Schema.org types: ItemList + ListItem with @id, position, name, description is valid.
• Empty-dict return and guard in graph-builder: consistent with other collectors.

---

The title-parsing approach is the root cause of both bugs 1 and 2; switching to header-row extraction resolves both in one change.
| Branch: feat/comparison-table-schema

[CamSoper]

Doing a human maintainer pass and landing on the same conclusions @claude did — including the column inversion, which I confirmed on the preview site. The Terraform page's JSON-LD currently reads:

"Terraform: Python, TypeScript, JavaScript, Go, C#, F#, Java, YAML | Pulumi IaC: HashiCorp Configuration Language (HCL)"

…which attributes Pulumi's languages to Terraform and HCL to Pulumi. Definitely want that fixed before this ships — structured data that's confidently wrong is worse than no structured data at all.

The header-row extraction approach @claude suggested resolves both the column swap and the verbose-name issue on aws-cdk / cdktf in one shot. Worth also picking up the hasPart wiring from WebPage to the ItemList while you're in there.

Ping me when it's ready for another look.

[claude]

Claude finished @CamSoper's task in 2m 49s —— View job

---

Fixes implemented

• Gather context and understand request
• Read current file contents
• Fix 1: Replace title-parsing with header-row extraction for product/competitor names
• Fix 2: Add hasPart wiring from WebPage to ItemList in graph-builder.html
• Commit and push

---

What changed

comparison-table-entity.html — replaced the title-parsing block (lines 7–19) with header-row extraction:

{{/* Extract column names from the table header row (always in correct column order) */}}
{{ $headerCells := split (index $allTableLines 0) "|" }}
{{ $productName := index $headerCells 2 | strings.TrimSpace }}
{{ $competitorName := index $headerCells 3 | strings.TrimSpace }}

Column names now come from the actual table (| Feature | Pulumi | Terraform |) rather than the h1 title. This fixes:

• Terraform page: was "Terraform: Python… | Pulumi IaC: HCL" → now correctly "Pulumi: Python… | Terraform: HCL"
• Crossplane page: labels were swapped → now correct
• AWS CDK / CDKTF: verbose names ("CDK for Terraform (CDKTF)") → now canonical short forms ("AWS CDK", "CDKTF")

The two top-level guards (/comparisons/ path and | Feature | content check) are now combined into a single if and at line 5, so the title-parsing block is gone entirely.

graph-builder.html — moved the comparison table collector to run before $webpage is appended to $graph. This allows a hasPart link to be wired into the WebPage node when an ItemList is present:

{{ $comparisonTable = partial "schema/collectors/comparison-table-entity.html" . }}
{{ if and $comparisonTable (ne $comparisonTable (dict)) }}
  {{ $webpage = merge $webpage (dict "hasPart" (dict "@id" "#comparison-table")) }}
{{ end }}

The $comparisonTable variable is then re-used at the original insertion point to append the entity to $graph — no double-invocation of the partial.

Branch: feat/comparison-table-schema |

[CamSoper]

Sorry, @alexleventer! It seems I accidentally triggered Claude and he just came along and fixed it. Feel free to revert that commit if you need to!

[CamSoper]

Cool idea — verified the single-table pages render clean ItemLists (opentofu, terraform, terraform/opentofu, aws-cdk, cdktf, cloudformation all match their row counts). Two bugs to sort out before this ships though, both isolated to the new collector.

1. Multi-table pollution on the Crossplane page

findRE in comparison-table-entity.html line 11 captures every pipe-prefixed line in the document, not just rows of the Feature table. Crossplane has three more tables after the Feature one, so their header and data rows get pulled into the ItemList.

I built the site locally and looked at the generated JSON-LD for /docs/iac/comparisons/crossplane/:

• numberOfItems is 22, should be 5
• Position 6 is named "Aspect" with description "Pulumi: **Pulumi** | Crossplane: **Crossplane**" (that's the second table's header row being treated as a data row)
• Position 18 is "When to Choose Pulumi" -- another table header
• Positions 19-22 are rows from the "When to Choose" table, not features

Fix -- truncate to the first table block before extracting lines:

{{ $afterHeader   := replaceRE `(?s)^.*?\| Feature \|` "| Feature |" .RawContent }}
{{ $firstTable    := index (split $afterHeader "\n\n") 0 }}
{{ $allTableLines := findRE `(?m)^\|.+\|` $firstTable }}

2. Bold markdown leaks into ItemList names/descriptions

The existing replaceRE calls strip HTML tags and markdown links, but not **bold** / *italic* emphasis. Crossplane uses bold in its feature column, so the ItemList ends up with names like "**Multi-language Support**" verbatim -- the asterisks leak into the schema payload.

Fix -- add emphasis stripping to $feature, $val1, $val2 around lines 32-39:

{{ $feature = replaceRE `\*+([^*]+)\*+` "$1" $feature }}
{{ $val1    = replaceRE `\*+([^*]+)\*+` "$1" $val1 }}
{{ $val2    = replaceRE `\*+([^*]+)\*+` "$1" $val2 }}

Why this matters

On Crossplane specifically the structured data is worse than having none -- feeds search engines and AI answer engines a 22-item "feature list" where several items are literally table-header text. Rich Results Test is likely to flag it, and LLM summaries of the page could surface the junk items as real features.

Everything else looks good. The header-row extraction fix in fd506f2 is clean, and the hasPart wiring in graph-builder.html resolves correctly in the emitted @graph.

[alexleventer]

Thanks for the careful review, @CamSoper — both fixes applied in 18795e9:

1. Multi-table pollution — added the first-table truncation (split $afterHeader "\n\n" | index 0) before the findRE. Verified locally on /docs/iac/comparisons/crossplane/: numberOfItems is now 5 (Multi-language Support, State Management, Automatic Drift Detection, Preview Changes, Platform Independence), and the stray header/"When to Choose" rows are gone.
2. Bold/italic leakage — added \*+([^*]+)\*+ stripping to $feature, $val1, $val2. "**Multi-language Support**" now renders as "Multi-language Support" in the JSON-LD.

Also re-checked the single-table pages (terraform: 21 items, opentofu: 19) — row counts unchanged, so the truncation doesn't affect pages with only one Feature table.