Add executable plugin guide and restructure Packages section (#18364)

[jkodroff]

Adds a new guide for authoring executable-based plugin packages, introduces a Packages section landing page (Pulumi Packages Guides), and refocuses publishing-packages.md on the public Pulumi Registry. Also renumbers the Packages nav weights to unique multiples of 10 and de-emphasizes native language packages outside Packaging Components.

Fixes #18364

[claude]

Docs review

Solid restructure. The new Packages landing page and the executable-plugin guide read clearly, the menu weights are clean multiples of 10, and the alias removal in content/docs/iac/concepts/packages/_index.md correctly matches the new page taking over /docs/iac/guides/building-extending/packages/. A handful of small things below.

content/docs/iac/guides/building-extending/packages/_index.md

• Awkward title (lines 2, 4, 5): title_tag, title, and h1 are all set to Pulumi Packages Guides, which reads as a noun pile-up. Consider tightening to something like Pulumi Packages or Authoring Pulumi Packages (the Packages menu name already conveys the section, and Guides is implied by the parent Building and Extending section).

  title_tag: \"Pulumi Packages\"
  meta_desc: Pulumi packages let you author infrastructure abstractions and consume them in any Pulumi language via source-based or executable-based plugins.
  title: Pulumi Packages
  h1: Pulumi Packages
  

• Redundant h1 (line 5): When h1 duplicates title, you can drop it — Hugo falls back to title. (See executable-plugin.md, which omits h1.)

content/docs/iac/guides/building-extending/packages/executable-plugin.md

• Inconsistent product name (line 106): Says ...publishing them to npm, PyPI, NuGet, and Maven is a lot of moving parts. Other mentions in the file (lines 125, 132, 143) say Maven Central. Pick one — Maven Central is the accurate product name.

  Cross-compiling on tag push, uploading archives, generating SDKs, and publishing them to npm, PyPI, NuGet, and Maven Central is a lot of moving parts. Pulumi publishes template repositories that solve all of it end-to-end.
  

• Em-dash density: I count ~15 em-dashes across the file (lines 10, 13, 20, 28, 62, 74, 100, 123, 126, 128, 132, 143, etc.). For reference docs this is within tolerance, but a few could be replaced with a period or comma to vary rhythm — particularly the back-to-back uses in the same paragraph (lines 10/13, 132).

• Optional: cross-link the Mermaid diagram (line 162): The runtime sequence diagram is great context. Consider adding a one-liner above it that names the components — e.g., "The CLI resolves the plugin from the schema, downloads the binary if not cached, and launches it as a gRPC subprocess." — so readers who skim past the diagram still get the takeaway. (You arguably already do this in the preceding paragraph; this is a nice-to-have.)

content/docs/iac/guides/building-extending/packages/publishing-packages.md

• Cross-link target (line 105 / diff context): The replaced bullet for pluginDownloadURL now links to ./executable-plugin/#plugindownloadurl. Verified the anchor exists in the new file (the H2 ## `pluginDownloadURL` produces the slug plugindownloadurl). Good.

Style/convention checks (clean)

• Heading case (Title Case for H1, sentence case for H2+) is consistent across the new files.
• Ordered lists use 1. per AGENTS.md. ✓
• Mermaid block uses the right code-fence syntax. ✓
• Code blocks have language specifiers. ✓
• Internal links resolve (spot-checked anchors and relative paths).
• Removing the iac-guides-packages entry from config/_default/menus.yml and re-defining it inline in the new _index.md is consistent with how other section landing pages are structured.

Verification I couldn't do in CI

• Trailing newlines (CI diff doesn't show them).
• Live render of the Mermaid diagram and the comparison tables.
• make lint / make build.

---

@claude — mention me if you'd like me to re-review after changes or dig deeper into any of these.

[pulumi-bot]

Your site preview for commit c8223ef is ready! 🎉

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

[pulumi-bot]

Lighthouse Performance Report

Commit: c8223ef | Metric definitions

Page	Device	Score	FCP	LCP	TBT	CLS	SI
Homepage	Mobile	🟡 68	2.5s	2.5s	812ms	0.010	6.8s
Homepage	Desktop	🟢 90	0.7s	1.0s	22ms	0.080	2.8s
Install Pulumi	Mobile	🔴 38	4.6s	6.0s	255ms	0.431	7.4s
Install Pulumi	Desktop	🟡 88	1.1s	1.4s	20ms	0.020	2.8s
AWS Get Started	Mobile	🟡 56	4.4s	5.8s	251ms	0.093	7.0s
AWS Get Started	Desktop	🟡 88	1.1s	1.4s	20ms	0.027	2.7s

[CamSoper]

Three small fixes pushed on top of your branch:

• executable-plugin.md: added ${NAME} to the pluginDownloadURL interpolation variable list (the CLI interpolates four, not three)
• executable-plugin.md: dropped the "historical" framing for the other plugin kinds -- converter, language, and tool are all still current, and analyzer was missing
• concepts/components/_index.md: fixed the #authoring-and-distributing-components anchor that this PR's heading rename broke

Feel free to revert anything you'd rather handle yourself. Approving.