AEO improvements for /what-is/ pages

[alexleventer]

Summary

Improves AI Answer Engine Optimization (AEO) and SEO across all 27 /what-is/ explainer pages.

Schema (JSON-LD) changes

• layouts/partials/schema/collectors/article-entity.html — reads about, keywords, and mentions from frontmatter instead of using a hardcoded global keywords string. Adds an about Thing entity to the TechArticle so each page has a real Wikipedia/Wikidata anchor.
• layouts/partials/schema/graph-builder.html — for type: what-is, additionally emits a FAQPage entity (@id: #faq) when the body contains question-style H2/H3 headings, so the same page can appear as both a TechArticle and FAQPage in SERP and AI tools.

Frontmatter changes (27 pages)

Every what-is-*.md and what-are-*.md page now has:

• lastmod: 2026-05-12 (so dates surface in schema and the visible "Updated" hero line)
• about: with a Wikipedia sameAs (anchors the page to a real entity in the knowledge graph)
• keywords: array (page-specific, replaces the hardcoded global keywords)

Content changes

• Tighter openings on CI/CD and Cloud Security — sub-50-word quotable definitions, no preamble.
• Heading hierarchy fix on CI/CD (was starting at H3 after the opener; now H2 throughout).
• Key takeaways (3-5 bullets, right after the opening definition) and Get started in 3 steps blocks added to 9 major concept pages: IaC, DevOps, CI/CD, Platform Engineering, IDP, Cloud Security, Serverless, Configuration Management, Secrets Management.
• List bullets normalized from * to - across all 27 touched files to satisfy the repo's markdown lint rule (~470 mechanical replacements — most of the diff line count).

The what-is-pulumi.md page only receives the frontmatter changes; content rewrites were reverted per request.

Verified

Hugo build verified locally. JSON-LD for what-is-infrastructure-as-code was inspected and confirmed:

• New about Thing with Wikipedia sameAs
• Page-specific keywords (replacing the hardcoded global string)
• Separate FAQPage entity in @graph with 5 questions extracted from question-style headings

Known caveat

The existing FAQ-entity parser treats every question-style H2 on the page as an FAQ entry, and the answer text is the full section body verbatim. On pages with long sections under question H2s (IaC, platform-engineering), some FAQ answers are 3k+ characters. The schema validates and Google accepts this, but if you want tighter Q&A pairs we'd need to refine the parser to look only inside an ## FAQ section. Worth a follow-up.

Test plan

• Run make build locally and confirm pages render
• Validate JSON-LD output for 2-3 sample pages in Google's Rich Results Test
• Spot-check the rendered Key takeaways and Get started sections on a major page
• Confirm no regression on pages that don't have question-style H2s (FAQPage should be absent)

🤖 Generated with Claude Code

[claude]

Docs review — AEO improvements for /what-is/ pages

Solid PR overall. The schema work is clean and the new "Key takeaways" + "Get started" sections genuinely improve both AEO and reader value. A handful of items to consider before merging:

Issues to address

1. Stale-targeted Wikipedia sameAs anchors

A few of the new about.sameAs URLs don't point to articles that match the page topic well, which weakens the entity-anchoring benefit you're going for:

• content/what-is/what-is-hashicorp-vault.md:11 — https://en.wikipedia.org/wiki/HashiCorp is the company article, not the product. https://en.wikipedia.org/wiki/HashiCorp#Vault (or, if it exists, Vault_(software)) would be a closer anchor for a page titled "What is HashiCorp Vault?".
• content/what-is/what-is-hitrust.md:9 — https://en.wikipedia.org/wiki/HITRUST is a redirect/stub at best. Worth verifying it resolves to substantive content; otherwise drop sameAs and keep just name, or point at HITRUST's own canonical URL.
• content/what-is/what-is-pulumi.md:10 — please confirm https://en.wikipedia.org/wiki/Pulumi actually exists as a standalone article. The Wikidata entry (`Q122864080`, already used in layouts/partials/schema/graph-builder.html:94) is a safer anchor.
• content/what-is/what-is-a-github-action-secret.md:9 — https://en.wikipedia.org/wiki/GitHub is fine but generic. If `GitHub_Actions` exists as its own article, that's a closer match.

Each is low-stakes individually, but the whole point of the about block is precise entity grounding — a bad sameAs is worse than no sameAs for knowledge-graph signals.

2. what-is-hashicorp-vault.md still uses H3 at the top level

This file uses ### What is HashiCorp Vault?, ### Key features…, ### Creating secrets…, etc. at content/what-is/what-is-hashicorp-vault.md:18,24,34,53,72,85. The PR fixed the same problem on what-is-ci-cd.md but didn't extend the fix here. Suggested for the first one:

```suggestion

What is HashiCorp Vault?

```

…and similarly for the other top-level H3s. The FAQ extractor only picks up H3s ending in `?` for non-FAQ pages, so promoting these also reduces noise in the FAQPage output.

3. lastmod: 2026-05-12 applied to pages that only received frontmatter changes

Roughly 18 of the 27 files (the various *-secrets, *-vault, what-is-yaml.md, etc.) get only the new about/keywords frontmatter, no body changes. Setting lastmod to today on those pages will surface them as "freshly updated" in sitemap/SERPs even though user-facing content didn't move. Two options:

• Drop `lastmod` from the frontmatter-only files (Hugo falls back to git commit date) and keep it only on the pages whose content actually changed (CI/CD, cloud security, IaC, IDP, DevOps, configuration management, secrets management, platform engineering, serverless).
• Or leave it as-is and accept the cost — they did technically change (schema-level). Defensible either way; flagging so it's a deliberate call.

Minor / verify

4. FAQPage extraction caveat on long sections — Already called out in the PR body. The H2-ending-in-? rule treats the entire body of (for example) ## What is platform engineering? as one FAQ answer (~1.5k+ chars). Google accepts it, but Bing/AI assistants prefer tighter Q/A pairs. The ## FAQ-scoped variant suggested in the PR description is the right cleanup.

5. Anchor slug change in what-is-ci-cd.md — heading text changed from ### CI/CD best practices to ## Best practices for CI/CD pipelines at content/what-is/what-is-ci-cd.md:62. Good promotion to H2, but the slug also changes (#cicd-best-practices → #best-practices-for-cicd-pipelines), silently breaking any deep links to the old anchor. Worth a quick grep for #cicd-best-practices across /content/docs, /content/product, and external references.

6. Em-dash density in new Key takeaways — Mostly fine, but content/what-is/what-is-cloud-security.md:20-26 and content/what-is/what-is-platform-engineering.md:22-28 each carry 3+ em-dashes in five bullets. Not a hard rule for docs (the em-dash limit is a blog-review heuristic), but the rhythm gets uniform across pages — consider varying punctuation on the next pass.

7. Schema empty-dict guard — layouts/partials/schema/graph-builder.html:36 uses (gt (len \$faqEntity) 0), which correctly handles the empty-dict fallback in layouts/partials/schema/collectors/faq-entity.html:170. Good defensive check; not all Hugo ifs would catch that.

Quick checks

• Wikipedia sameAs URLs (Switch to using typedoc for TypeScript documentation. #1) — verify each resolves to a substantive article.
• HashiCorp Vault H3→H2 (Update in the wake of renamepocalypse #2).
• Decide on lastmod policy (Improve our TypeScript documentation story #3).
• Grep for external dependents of #cicd-best-practices (Use a proper service/daemon, not screen #5).

Style, code examples (pulumi new aws-typescript, pulumi config set --secret, etc.), list-bullet conversion *→-, the 1. ordered-list convention, and the overall JSON-LD output structure all look correct. Hugo build passing locally is a strong signal too.

Mention me (@claude) if you want a re-review or want me to push fixes for any of these.

[alexleventer]

@claude - review this PR pls

[alexleventer]

@claude - another look pls