seo: add FAQ sections to Language Essentials series to earn FAQPage schema

[workprentice]

What

Adds a "Frequently asked questions" section (3 Q&A pairs each) to the 6 leaf pages under content/docs/iac/guides/basics/language-essentials/: variables, conditionals, loops, functions, classes, and packages-and-dependencies.

Why

Every page in this series is type: docs and .IsPage, so each already auto-qualifies for supplemental FAQPage schema in layouts/partials/schema/graph-builder.html with zero frontmatter flag needed. But the collector (schema/collectors/faq-entity.html) only picks up ##/### headings ending in ?, and none of these pages had one — every existing heading ("Where you have seen this before", "The syntax", "What to watch out for", etc.) is declarative. Live-page audit confirmed the gap: no FAQPage entity was rendering on any of the 6 pages.

FAQPage is one of the two highest-leverage schema types for LLM/answer-engine citation, and this series sits squarely in Tier 3 educational/GEO content, so it's a good target for this.

Why a dedicated section instead of rephrasing existing headings

STYLE-GUIDE.md restricts trailing-? headings to a named exception: a "Frequently asked questions" section. Rephrasing "What to watch out for" into a question would violate that, and several of those existing sections contain {{< chooser >}}/{{% choosable %}} shortcodes and code fences that would leak into acceptedAnswer.text if pulled into an answer span anyway. Instead, each page gets a new ## Frequently asked questions H2 (matching the style guide's exact wording) placed immediately before ## Next steps, with ### question headings and clean, answer-first prose, following the same pattern already established across content/docs/iac/comparisons/*.md (e.g. crossplane.md).

Out of scope (and why)

• _index.md for this section is untouched. It's a Hugo section bundle, so .IsPage is false, and it can never carry FAQPage schema regardless of content.
• HowTo schema was considered and dropped. It's gated to .Type == "blog" in graph-builder.html, so a content/docs/ page can never carry it.

Verification

Ran the changes through an isolated Hugo harness (schema/graph-builder.html plus its full dependency chain and the real content copied verbatim into a minimal standalone site, per the team's schema-harness playbook), since hugo build on the full checkout fails on uncommitted CI-built CSS/icon assets unrelated to this change.

Result: all 6 rendered pages emit a FAQPage entity in the @graph with 3 Question/acceptedAnswer pairs each (18 total), and a parse of every acceptedAnswer.text confirms no leaked markdown — no stray #-prefixed headings, code fences, table pipes, or list markers in any answer.

Also ran locally and confirmed clean:

• node ./scripts/lint/lint-markdown.js — 0 errors across 1846 files.
• ./scripts/prettier.sh --check on the 6 changed files — all match Prettier style.
• Pre-commit hook (lint-staged) ran clean on commit.

---

🧠 This PR was created by workprentice.

[github-actions]

Pre-merge Review — Last updated 2026-08-22T00:25:48Z

Tip

Summary: This PR adds a three-question "Frequently asked questions" section to each of the six pages in the Language Essentials series (classes, conditionals, functions, loops, packages-and-dependencies, variables), placed consistently just above each page's "Next steps" section so the pages earn FAQPage structured data. The mechanism checks out: layouts/partials/schema/graph-builder.html auto-qualifies regular docs pages for FAQ schema with no frontmatter opt-in, and schema/collectors/faq-entity.html picks up H3 headings ending in ? — every added heading does, so all 18 questions will be emitted. The wrongness that would hurt a reader here is a compressed FAQ answer that overstates or contradicts the page body it summarizes (an FAQ answer is the part most likely to be quoted out of context by a search or answer engine), so this review focused on fact-checking each answer against Pulumi docs and source, and on checking the six new sections against each other for contradictory guidance. Nothing blocking surfaced: the answers restate what the page bodies and the linked concept docs already say, and the six sections agree with one another on the shared themes (outputs aren't known at program time, components vs. plain functions, pulumi package add SDK generation). Passes run: fact verification of the extracted claims, a cross-sibling read of all five peer pages for each file, frontmatter and Hugo preflight, internal-link and shortcode checks, and pattern-based prose linting.

Review confidence:

Dimension	Level	Notes
mechanics	HIGH
facts	HIGH
cross-sibling consistency	HIGH

Investigation log

• Cross-sibling reads: 5 of 5 siblings
• External claim verification: 28 of 31 claims verified (1 unverifiable, 0 contradicted) · 4 specialists (numerical, cross-reference, capability, framing); 0 cross-specialist corroborations · routed: 0 inline, 25 Pass 1, 0 Pass 2, 6 Pass 3 (verified 5, contradicted 0, unverifiable 1).
• Cited-claim spot-checks: not run (no cited claims)
• Frontmatter sweep: ran on body + meta_desc
• Temporal-trigger sweep: not run (no trigger words)
• Code execution: not run (no static/programs/ change)
• Code-examples checks: not run (no fenced code blocks in content files)
• Editorial-balance pass: not run (not under content/blog/)

🚨 Outstanding	⚠️ Low-confidence	💡 Pre-existing	✅ Resolved
0	2	0	0

🔍 Verification trail

32 claims extracted · 28 verified · 2 unverifiable · 0 contradicted

• L334 in content/docs/iac/guides/basics/language-essentials/classes.md "Classes are entirely optional in Pulumi." → ✅ verified (evidence: Pulumi programs can be written as plain functions and resource declarations without defining any classes; classes (ComponentResource subclasses) are only needed when packaging resources into a reusable component. This matches Pulumi's…; source: repo:content/docs/iac/guides/basics/language-essentials/classes.md (surrounding context, lines 332-334))
• L334 in content/docs/iac/guides/basics/language-essentials/classes.md "In Pulumi, a class is only needed when you want to package resources into a reusable, named component that other code can create and reference as a unit." → ➖ not-a-claim (evidence: The line is a paraphrase/summary of the page's own FAQ answer: "You only reach for a class when you want to package resources into a reusable, named component that other code can create and reference as a unit." This is the author's own…; source: repo:content/docs/iac/guides/basics/language-essentials/classes.md)
• L334 in content/docs/iac/guides/basics/language-essentials/classes.md "Most day-to-day Pulumi infrastructure code is plain functions and resource declarations rather than classes." → 🤷 unverifiable (evidence: This is a subjective positioning/style claim about typical developer usage patterns rather than a specific factual assertion with an authoritative checkable source. General Pulumi documentation and community sources confirm that Pulumi…; source: WebSearch ran query "Pulumi infrastructure code functions vs classes best practices"; results describe general Pulumi language features but do not address the specific proportion/framing claimed)
• L338 in content/docs/iac/guides/basics/language-essentials/classes.md "A Pulumi ComponentResource exposes its child resources' combined outputs through a single interface using registerOutputs (or RegisterOutputs in C#)." → ✅ verified (evidence: The components guide confirms: "Outputs in a component must be registered with the Pulumi IaC engine by calling registerOutputs." and for C#: "Finally, calling this.RegisterOutputs signals Pulumi that the component creation process…; source: repo:content/docs/iac/guides/building-extending/components/build-a-component.md)
• L338 in content/docs/iac/guides/basics/language-essentials/classes.md "In C#, the equivalent method to registerOutputs is named RegisterOutputs." → ✅ verified (evidence: In pulumi/pulumi-dotnet's sdk/Pulumi/Resources/ComponentResource.cs, the method is defined as protected void RegisterOutputs() (with overloads RegisterOutputs(IDictionary<string, object?>) and RegisterOutputs(Task<...>))…; source: gh api repos/pulumi/pulumi-dotnet/contents/sdk/Pulumi/Resources/ComponentResource.cs)
• L342 in content/docs/iac/guides/basics/language-essentials/classes.md "Pulumi generates an SDK in whichever language the consumer is using when they run pulumi package add against a source-based component's Git URL, including…" → ✅ verified (evidence: Sibling doc content/docs/iac/guides/building-extending/components/packaging-components.md states: "Pulumi introspects the package and generates an SDK in the consumer's language when they run pulumi package add, so the components are…; source: pulumi/docs:content/docs/iac/guides/building-extending/components/packaging-components.md)
• L342 in content/docs/iac/guides/basics/language-essentials/classes.md "Pulumi generates an SDK in whichever language the consumer is using when they run pulumi package add against a source-based package's Git URL." → ✅ verified (evidence: The auto-generated CLI reference for pulumi package add states: "This command locally generates an SDK in the selected Pulumi language..." and separately documents Git repo references as a supported provider form ("When is a…; source: repo:content/docs/iac/cli/commands/pulumi_package_add.md (auto-generated from pulumi/pulumi CLI markdown))
• L342 in content/docs/iac/guides/basics/language-essentials/classes.md "A plain npm- or PyPI-style native language package only works in the language it was published for." → ✅ verified (evidence: This is a general, well-established fact about npm and PyPI: packages published to npm are consumable only via Node.js/JS/TS tooling, and PyPI packages only via Python tooling — they are not cross-language by design. The doc uses this as…; source: General knowledge of npm/PyPI package ecosystem semantics; corroborated by surrounding doc context in content/docs/iac/guides/basics/language-essentials/classes.md describing pulumi package add as generating SDKs "in whichever language they're using" as the contrasting case.)
• L270 in content/docs/iac/guides/basics/language-essentials/conditionals.md "In Pulumi, a resource can be made conditional by wrapping its declaration in a plain if statement in the host programming language, with no special…" → ✅ verified (evidence: The page demonstrates across TypeScript, Python, Go, C#, and Java that a resource is made conditional by wrapping new aws.s3.Bucket(...) (or equivalent) inside a plain if (pulumi.getStack() === "production") { ... } block, with no…; source: repo:content/docs/iac/guides/basics/language-essentials/conditionals.md)
• L274 in content/docs/iac/guides/basics/language-essentials/conditionals.md "In Pulumi, an ordinary if statement replaces the role that Terraform's count = 0 plays for conditional resource creation." → ✅ verified (evidence: Pulumi's official blog states this exact comparison: "In order to conditionally create a resource in Terraform, we had to set its count to either 0 or the desired AZ count" and that in Pulumi "using familiar if statements instead of the…; source: https://www.pulumi.com/blog/from-terraform-to-infrastructure-as-software/)
• L274 in content/docs/iac/guides/basics/language-essentials/conditionals.md "Because Pulumi uses a real programming language rather than a declarative block, references to a conditionally created resource stay single values instead of…" → ✅ verified (framing: Source documents Terraform's zero-or-one-element list pattern explicitly; Pulumi's contrasting single-value behavior follows directly from it being a…; evidence: Terraform docs confirm that conditional resource creation via count = condition ? 1 : 0 produces a zero-or-one-element list requiring functions like one() to extract a single value: "Because the aws_instance resource above has the…; source: https://developer.hashicorp.com/terraform/language/functions/one)
• L278 in content/docs/iac/guides/basics/language-essentials/conditionals.md "In Pulumi, you cannot directly branch an if statement on a resource output." → ✅ verified (evidence: The same doc states this as core Pulumi behavior: "You can't branch an if statement on a resource output. An output's value isn't known while your program is running... If a decision genuinely depends on a value that only exists after…; source: repo:content/docs/iac/guides/basics/language-essentials/conditionals.md)
• L278 in content/docs/iac/guides/basics/language-essentials/conditionals.md "If a decision depends on a value produced by another resource in Pulumi, it should be made inside an apply callback instead of at the top level of the…" → ✅ verified (evidence: The inputs-outputs docs explain outputs are asynchronous values "not initially known but become known once an infrastructure resource has completed provisioning" and that apply "allows you to access a single output's plain value,"…; source: content/docs/iac/concepts/inputs-outputs/_index.md)
• L283-285 in content/docs/iac/guides/basics/language-essentials/functions.md "A plain function should be used when grouping or parameterizing a handful of resource declarations, while a component should be used once that group needs…" → ✅ verified (evidence: The claim is a close paraphrase of the source document's own text at line 285: "Reach for a plain function when you just want to group or parameterize a handful of resource declarations, and reach for a component once that group needs…; source: repo:content/docs/iac/guides/basics/language-essentials/functions.md and repo:content/docs/iac/concepts/components/_index.md)
• L285 in content/docs/iac/guides/basics/language-essentials/functions.md "A function is a lighter-weight option than a component." → ✅ verified (framing: Source frames it as "function is the better choice" for simpler cases without the encapsulation/reuse overhead of a component; "lighter-weight option" is a…; evidence: Pulumi's own docs guide "When to Build a Component" is described as helping users "Understand what a component gives you that a plain function cannot, and when a function is the better choice," and the "Build a Component" page notes…; source: https://www.pulumi.com/docs/iac/guides/building-extending/)
• L287-289 in content/docs/iac/guides/basics/language-essentials/functions.md "The closest analogue to a Terraform module is a Pulumi component resource." → ✅ verified (evidence: Pulumi's official Component Resources documentation states: "Components are analogous to Terraform modules and AWS CDK Constructs," directly confirming the claim's comparison.; source: https://www.pulumi.com/docs/iac/concepts/components/)
• L289 in content/docs/iac/guides/basics/language-essentials/functions.md "A Pulumi component resource gets its own name, state entry, and combined outputs." → ✅ verified (evidence: Pulumi docs confirm components are "instantiated exactly like any other Pulumi resource: with a name," appear as their own entries in the resource tree/state (shown in pulumi up output), and authors "register outputs" via…; source: repo:content/docs/iac/concepts/components/_index.md)
• L289 in content/docs/iac/guides/basics/language-essentials/functions.md "A plain function in a Pulumi program is a lighter-weight grouping mechanism with no state identity of its own." → ✅ verified (evidence: Pulumi's own components docs state "A component is a logical grouping of Pulumi resources that is exposed as a single Pulumi resource," meaning it gets a name/state entry in the resource graph, unlike a plain function which is ordinary…; source: repo:content/docs/iac/concepts/components/_index.md)
• L291-293 in content/docs/iac/guides/basics/language-essentials/functions.md "An output does not need to be unwrapped before being passed to a function; Pulumi resolves the output's value later, once it is known." → ✅ verified (framing: Source explains outputs generally resolve once known and are consumed via SDK methods; claim narrows this to the specific case of passing an output into a…; evidence: The linked inputs-outputs page states: "Outputs work like promises or futures: they represent values that are not initially known but become known once an infrastructure resource has completed provisioning... You must use methods…; source: content/docs/iac/concepts/inputs-outputs/_index.md)
• L344-346 in content/docs/iac/guides/basics/language-essentials/loops.md "Replacing Terraform's for_each meta-argument in Pulumi requires no separate meta-argument; instead, you use a normal loop or comprehension over a list or map…" → ✅ verified (evidence: Multiple sources confirm Pulumi has no for_each-style meta-argument; instead resources are created by iterating with native language constructs (e.g., "Pulumi: Dynamic resource creation with real programming const regions = [...]; const…; source: https://lucaberton.com/blog/terraform-vs-pulumi-2026/)
• L348-350 in content/docs/iac/guides/basics/language-essentials/loops.md "To keep resource names stable when creating resources in a loop in Pulumi, you should build each resource's logical name from a stable key drawn from your…" → ✅ verified (evidence: names.md confirms the underlying mechanism the claim relies on: "Pulumi uses the logical name to track the identity of a resource through multiple deployments... changing the name of a resource will create a new resource and delete the…; source: repo:content/docs/iac/concepts/resources/names.md)
• L352-354 in content/docs/iac/guides/basics/language-essentials/loops.md "You can call pulumi.all([...]) to combine several Pulumi outputs and perform iteration inside the callback once the values are resolved." → ✅ verified (evidence: The inputs-outputs "all" doc states: "the all function acts like an apply across many resources, allowing you to retrieve and use multiple outputs at the same time. The all function waits for all output values to become available…; source: repo:content/docs/iac/concepts/inputs-outputs/all.md)
• L352-354 in content/docs/iac/guides/basics/language-essentials/loops.md "You cannot loop directly over a Pulumi resource output." → ✅ verified (evidence: The doc itself explains the underlying mechanism consistent with well-known Pulumi Output semantics: "Not directly, since an output isn't a concrete value while your program runs. Call .apply() on a single output, or pulumi.all([...]) to…; source: repo:content/docs/iac/guides/basics/language-essentials/loops.md (L352-354); consistent with /docs/iac/concepts/inputs-outputs/ Output/apply semantics)
• L69-71 in content/docs/iac/guides/basics/language-essentials/packages-and-dependencies.md "Manual installation via pulumi plugin install is intended for cases like pre-fetching plugins in CI, working offline, or pinning a specific plugin version…" → ✅ verified (framing: Source describes plugin install's mechanics (manual, version-pinning, file-based install) generally; the claim's specific use-case list (CI pre-fetch…; evidence: The pulumi CLI source for plugin install states: "This command is used to manually install plugins required by your program... If VERSION is specified, it cannot be a range; it must be a specific number." It also supports a --file…; source: gh api repos/pulumi/pulumi/contents/pkg/cmd/pulumi/plugin/plugin_install.go)
• L71 in content/docs/iac/guides/basics/language-essentials/packages-and-dependencies.md "Running pulumi plugin install is not a step needed in ordinary day-to-day Pulumi development." → ✅ verified (evidence: Pulumi engine source (pkg/engine/update.go) shows automatic plugin installation logic (installPluginFunc, triggered on workspace.MissingError, gated by a DisableAutomaticPluginAcquisition env var) invoked during update/preview…; source: gh search code --owner pulumi (pkg/engine/update.go, pkg/workspace/plugin.go in pulumi/pulumi))
• L75 in content/docs/iac/guides/basics/language-essentials/packages-and-dependencies.md "The pulumi package add mechanism for generating a local SDK from a plugin or schema is the same mechanism source-based component packages use." → ✅ verified (framing: Source describes the shared internal call path (ProviderFromSource/InstallPlugin) used across pulumi package add, get-schema, publish, and schema binding…; evidence: Pulumi's internal architecture doc (pulumi/pulumi docs/architecture/plugins.md) states: "pulumi package add ends up calling packages.ProviderFromSource, which calls pkg/workspace.InstallPlugin. That means it does not work on…; source: gh api repos/pulumi/pulumi/contents/docs/architecture/plugins.md (pulumi/pulumi, docs/architecture/plugins.md))
• L79 in content/docs/iac/guides/basics/language-essentials/packages-and-dependencies.md "After a component is published to the Pulumi Private Registry, teammates can discover the package in the registry and generate an SDK for it in whichever…" → ✅ verified (evidence: Sibling docs confirm this exact workflow. private-registry.md: "Platform engineers publish components to the private registry so that developers can discover them, browse auto-generated API documentation, and use them in their Pulumi…; source: repo:content/docs/idp/concepts/private-registry.md and repo:content/docs/iac/guides/building-extending/components/packaging-components.md)
• L79 in content/docs/iac/guides/basics/language-essentials/packages-and-dependencies.md "Teammates can discover a package published to the Pulumi Private Registry and generate an SDK for it in whichever language they're using." → ✅ verified (framing: Source describes the general private registry discover+consume workflow across "every Pulumi language"; claim's specific framing (teammates discover and…; evidence: Pulumi docs confirm this workflow: "Pulumi Private Registry is the source of truth for an organization's infrastructure building blocks... Platform engineers publish components to the private registry so that developers can discover…; source: repo:content/docs/idp/concepts/private-registry.md; repo:content/docs/iac/guides/building-extending/components/packaging-components.md)
• L328 in content/docs/iac/guides/basics/language-essentials/variables.md "Per-stack inputs that used to live in a Terraform variable block instead come from Pulumi stack configuration, which is read at the top of the program and…" → ✅ verified (evidence: The config concepts page confirms: stack-specific values are stored in Pulumi.<stack-name>.yaml and are read into a variable via pulumi.Config()/config.require() "and use it the same way you'd use any other variable," matching the…; source: content/docs/iac/concepts/config.md)
• L332 in content/docs/iac/guides/basics/language-essentials/variables.md "A Pulumi resource output value isn't known while the program runs; it only resolves once the resource is created or updated." → ✅ verified (evidence: The linked page /docs/iac/concepts/inputs-outputs/ states: "Outputs are values that are only known after a resource is created. For example, if you are creating an aws.ec2.Vpc resource, the VPC ID is an output — you cannot choose this…; source: repo:content/docs/iac/concepts/inputs-outputs/_index.md)
• L272 in content/docs/iac/guides/basics/language-essentials/conditionals.md "Question headings that contain inline code carry their backticks into the generated FAQ question name" → 🤷 unverifiable (evidence: layouts/partials/schema/collectors/faq-entity.html builds each Question.name from .RawContent, trimming only the ### prefix, so a heading like ### What replaces `count = 0` in Pulumi? emits the backticks literally in the structured data. Whether that materially affects how an answer engine renders the question is not something this review can confirm.; source: repo:layouts/partials/schema/collectors/faq-entity.html (lines 59-73, 132-139))
• L336 in content/docs/iac/guides/basics/language-essentials/variables.md "Declaring an explicit type for public function signatures and component inputs in Pulumi programs provides IDE completion and catches mismatches at compile…" → ➖ not-a-claim (evidence: This is a general explanatory statement about static typing benefits (IDE completion, compile-time error catching) in typed languages used with Pulumi (TypeScript, C#, Java, Go). It's a well-established, non-Pulumi-specific programming…; source: repo:content/docs/iac/guides/basics/language-essentials/variables.md)

🚨 Outstanding in this PR

No outstanding findings in this PR.

⚠️ Low-confidence

Review each and resolve as appropriate — these don't block the PR.

• [L334] content/docs/iac/guides/basics/language-essentials/classes.md — "Most day-to-day Pulumi infrastructure code is plain functions and resource declarations rather than classes." — verdict: unverifiable. This is a claim about how the typical Pulumi program is written, and there's no measurable source behind it — no survey, no corpus analysis. It isn't a capability or spec claim, so it doesn't block anything, and the surrounding sentence ("Classes are entirely optional in Pulumi") is verified and does the real work. Nothing to fix unless you want to soften it. Author question: is "most day-to-day infrastructure code" a positioning line you're comfortable standing behind unsourced, or would you rather drop it and let "entirely optional" carry the answer on its own?
• [L272] content/docs/iac/guides/basics/language-essentials/conditionals.md — question headings that contain inline code (### What replaces `count = 0` in Pulumi?, plus ### How do I replace `for_each` when I move from Terraform to Pulumi? in loops.md L344 and ### Do I still need to run `pulumi plugin install`? in packages-and-dependencies.md L69) carry their backticks straight into the generated structured data. The FAQ collector builds each Question.name from the raw markdown and strips only the ### prefix, so the emitted question reads What replaces `count = 0` in Pulumi? — backticks and all — even though the on-page heading renders correctly. If you'd rather the structured data read cleanly, drop the code formatting in the heading only and keep it in the answer body, e.g. ### What replaces count = 0 in Pulumi?. Judgment call: the on-page heading reads better with the code formatting, so this is a tradeoff, not a defect.

💡 Pre-existing issues in touched files (optional)

No pre-existing issues in touched files.

✅ Resolved since last review

No items resolved since the last review.

📜 Review history

• 2026-08-22T00:25:48Z — No blockers: the 18 new FAQ answers check out against the page bodies and linked concept docs, the six sections agree with each other, and the added H3s will all emit FAQ structured data; two low-confidence notes (an unsourced "most day-to-day code" positioning line, and inline code in three question headings leaking backticks into the generated question names). (3baf44b)

---

• Refresh this review — comment @claude #update-review. Say what you fixed, or which finding you dispute and why; both work in the same mention.
• Ask for anything else — comment @claude with no hashtag (questions, one-off fixes). Leaves this review untouched.

Important

Please don't hide, resolve, or delete this comment! It breaks things!

📖 How pre-merge review works — the full lifecycle, short-circuits, and escape hatches.

[pulumi-bot]

Your site preview for commit 3baf44b is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-21064-3baf44b2.s3-website.us-west-2.amazonaws.com

Changed pages:

• /docs/iac/guides/basics/language-essentials/classes/
• /docs/iac/guides/basics/language-essentials/conditionals/
• /docs/iac/guides/basics/language-essentials/functions/
• /docs/iac/guides/basics/language-essentials/loops/
• /docs/iac/guides/basics/language-essentials/packages-and-dependencies/
• /docs/iac/guides/basics/language-essentials/variables/