Docs Review

Solid first pass at a Pulumi HCL reference — comprehensive coverage of blocks, expressions, functions, and Terraform-compat differences. A handful of issues to address before merge.

Style guide (AGENTS.md)

Heading case — per AGENTS.md, H2+ must be sentence case. The new _index.md has Title Case H2s:

In content/docs/iac/languages-sdks/hcl/_index.md:

• Line 85: ## Pulumi Programming Model →

  ## Pulumi programming model
  

• Line 107: ## HCL Packages →

  ## HCL packages
  

(Note: sibling _index.md files like go/, python/, and yaml/ also break this rule, so updating the new files alone keeps inconsistency. Worth flagging either way — your call.)

Non-canonical link paths

Per AGENTS.md, "Links within `/docs/` must use the full canonical path." The reference uses non-canonical paths that currently rely on alias redirects:

In content/docs/iac/languages-sdks/hcl/hcl-language-reference.md:

• Line 81: [Pulumi secret](/docs/concepts/secrets/) — canonical path is /docs/iac/concepts/secrets/.
• Line 239: [resource options](/docs/concepts/options/) — canonical path is /docs/iac/concepts/resources/options/.
• Line 741: [Pulumi secrets](/docs/concepts/secrets/) — canonical path is /docs/iac/concepts/secrets/.

Frontmatter

Empty aliases: field in content/docs/iac/languages-sdks/hcl/hcl-component-reference.md (line 15) — drop the empty key. The lone aliases: line right before the closing --- should be removed.

Menu weight conflict in content/docs/iac/languages-sdks/hcl/_index.md (line 15):

The languages menu in content/docs/iac/languages-sdks/_index.md already assigns weight: 7 to "Overview". Adding HCL at weight 7 creates a tie. Suggest bumping to weight: 8.

Spelling

hcl-language-reference.md line 454: "BitBucket" → "Bitbucket" (Atlassian's product name uses a single capital):

```suggestion
| Bitbucket shorthand | `bitbucket.org/org/repo` |
```

Suggestions (non-blocking)

• _index.md line 32: consider the {{< github-card >}} shortcode for the pulumi-labs/pulumi-hcl reference, consistent with other repo callouts in the docs.
• The resource options table (lines 239–262 of hcl-language-reference.md) lists several Pulumi-specific options (replace_with, hide_diffs, replacement_trigger) without links to definitions. A pointer to /docs/iac/concepts/resources/options/ for the full canonical list would help readers cross-reference.
• The pulumi_stackreference block syntax is a useful pattern but somewhat hidden in its own subsection — consider cross-linking from the Outputs or Resources sections.
• The H1s Pulumi HCL component reference and Pulumi HCL reference are sentence case; per AGENTS.md, H1 should be Title Case. Sibling H1s in this section are mixed (e.g., Pulumi YAML Component reference), so this is a consistency call.

Mention me (@claude) for additional reviews or fixes.

Your site preview for commit c706690 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-18759-c706690e.s3-website.us-west-2.amazonaws.com

Docs review

Solid first cut at the Pulumi HCL reference docs — three new files totaling ~970 lines of well-organized reference material. Heading style, frontmatter, menu wiring, and aliases all look consistent with the sibling yaml/ reference docs. Below are the issues I found.

content/docs/iac/languages-sdks/hcl/hcl-language-reference.md

Resource options text mentions options that aren't in the table (line 33)

The intro at line 33 lists protect and ignore_changes as examples of top-level Pulumi resource options:

resource blocks support the full set of Pulumi resource options as top-level attributes (with snake_case names — for example retain_on_delete, protect, ignore_changes).

But the resource-options table further down (around lines 162–175) doesn't include protect or ignore_changes — those appear only as prevent_destroy / ignore_changes inside the lifecycle block. Either the example list should be revised to use options that are actually in the table (e.g., retain_on_delete, parent, aliases), or the table should be expanded to include protect if it's also valid as a top-level attribute. As written, a reader who tries protect = true at the top level may be left guessing.

call block example uses an unclear method name (lines ~485–497)

resource "aws_instance" "web" {
  ami           = "ami-12345678"
  instance_type = "t3.micro"
}

call "web" "getPasswordData" {
}

output "password_data" {
  value = call.web.getPasswordData.password_data
}

The current example uses call_custom / provider_value, which doesn't communicate what call is for. A real-world method (e.g., AWS's getPasswordData) makes the feature concrete. Also worth clarifying in the surrounding prose: when two resources share a logical name across types, how is the call block disambiguated? The current text only says the first label is "the logical name of a declared resource."

Optional: link the first mention of Terraform

Line 21 introduces Terraform-like syntax without a hyperlink. First-mention linking is more strictly enforced for blogs than reference docs, but a single link to Terraform's docs near the top of the reference would be a nice courtesy for readers new to HCL. (The same applies to _index.md line 7.)

content/docs/iac/languages-sdks/hcl/hcl-component-reference.md

No issues — concise, well-structured, and the cross-links to the language reference (#variables, #outputs) resolve to real anchors.

content/docs/iac/languages-sdks/hcl/_index.md

No issues. Frontmatter, menu weight (7, distinct from siblings), and the alias /docs/languages-sdks/hcl/ look correct.

Cross-cutting / nits

• PR description is empty. Worth filling in a sentence about what's being added and which CLI version this targets, since the docs claim 3.235.0+ as the requirement.
• languages menu weight mismatch (_index.md line 14): the iac weight is 7, but the languages menu weight is 8. Other languages match across both menus (e.g., Python=2/2). Probably harmless, but you may want to set both to 7 for consistency.

Mention me (@claude) if you'd like a second pass or fixes applied.