Restructure IaC docs hierarchy for better discoverability (#15366)

jkodroff · claude · kramhuber · web-flow · commit 18d6cd617832 · 2025-06-23T12:13:10.000-04:00
* Restructure iac docs hierarchy for better discoverability - Move Automation API and Policy as Code (CrossGuard) to top-level sections as key product features - Elevate Extending Pulumi to top-level category positioned after Adopting Pulumi - Move Building a Component guide directly under Using Pulumi for easier access - Update navigation weights and menu structure to reflect new hierarchy - Fix internal links and references affected by the restructuring Fixes #15365 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> Co-authored-by: Mark <mark@pulumi.com>
diff --git a/content/docs/iac/automation-api/_index.md b/content/docs/iac/automation-api/_index.md
@@ -7,9 +7,9 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
         name: Automation API
-        parent: iac-using-pulumi
-        weight: 3
-        identifier: iac-using-pulumi-automation-api
+        parent: iac-home
+        weight: 55
+        identifier: iac-automation-api
 aliases:
 - /docs/guides/automation-api/
 - /docs/using-pulumi/automation-api/
diff --git a/content/docs/iac/automation-api/automation-api.png b/content/docs/iac/automation-api/automation-api.png
diff --git a/content/docs/iac/automation-api/concepts-terminology.md b/content/docs/iac/automation-api/concepts-terminology.md
@@ -8,7 +8,7 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
         name: Concepts
-        parent: iac-using-pulumi-automation-api
+        parent: iac-automation-api
         weight: 2
 aliases:
 - /docs/guides/automation-api/concepts-terminology/
diff --git a/content/docs/iac/automation-api/getting-started-automation-api.md b/content/docs/iac/automation-api/getting-started-automation-api.md
@@ -8,7 +8,7 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
         name: Getting Started
-        parent: iac-using-pulumi-automation-api
+        parent: iac-automation-api
         weight: 1
 aliases:
 - /docs/guides/automation-api/getting-started-automation-api/
diff --git a/content/docs/iac/crossguard/_index.md b/content/docs/iac/crossguard/_index.md
@@ -8,9 +8,9 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
         name: Policy as code
-        parent: iac-using-pulumi
-        weight: 4
-        identifier: iac-using-pulumi-policy
+        parent: iac-home
+        weight: 60
+        identifier: iac-policy
 aliases:
 - /docs/guides/crossguard/
 - /policy-as-code/
diff --git a/content/docs/iac/crossguard/api-policy-manager.md b/content/docs/iac/crossguard/api-policy-manager.md
@@ -8,7 +8,7 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
         name: Policy manager
-        parent: iac-using-pulumi-policy-compliance
+        parent: iac-policy-compliance
         weight: 1
 aliases:
     - /docs/using-pulumi/crossguard/api-policy-manager/
diff --git a/content/docs/iac/crossguard/awsguard.md b/content/docs/iac/crossguard/awsguard.md
@@ -9,7 +9,7 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
         name: AWSGuard
-        parent: iac-using-pulumi-policy
+        parent: iac-policy
         weight: 6
 aliases:
 - /docs/guides/crossguard/awsguard/
diff --git a/content/docs/iac/crossguard/best-practices.md b/content/docs/iac/crossguard/best-practices.md
@@ -8,7 +8,7 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
         name: Best practices
-        parent: iac-using-pulumi-policy
+        parent: iac-policy
         weight: 5
 aliases:
 - /docs/guides/crossguard/best-practices/
diff --git a/content/docs/iac/crossguard/compliance-ready-policies-aws.md b/content/docs/iac/crossguard/compliance-ready-policies-aws.md
@@ -1,19 +1,19 @@
 ---
-title_tag: "Compliance Ready Policies (Aws) | CrossGuard"
-meta_desc: This page contains the list of Compliance Ready Policies for Aws.
-title: Compliance Ready Aws Policies
-h1: List of Compliance Ready Policies for Aws
+title_tag: "Compliance Ready Policies (AWS) | CrossGuard"
+meta_desc: This page contains the list of Compliance Ready Policies for AWS.
+title: Compliance Ready AWS Policies
+h1: List of Compliance Ready Policies for AWS
 meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
         name: AWS Policies
-        parent: iac-using-pulumi-policy-compliance
+        parent: iac-policy-compliance
         weight: 2
 aliases:
     - /docs/using-pulumi/crossguard/compliance-ready-policies-aws/
     - /docs/iac/packages-and-automation/crossguard/compliance-ready-policies-aws/
 ---
-There's a total of 93 Compliance Ready Policies for the Aws provider.
+There's a total of 93 Compliance Ready Policies for the AWS provider.
 
 All those policies are available in the `@pulumi/aws-compliance-policies` package.
 
diff --git a/content/docs/iac/crossguard/compliance-ready-policies-awsnative.md b/content/docs/iac/crossguard/compliance-ready-policies-awsnative.md
@@ -7,7 +7,7 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
         name: AWS Cloud Control Policies
-        parent: iac-using-pulumi-policy-compliance
+        parent: iac-policy-compliance
         weight: 3
 aliases:
     - /docs/using-pulumi/crossguard/compliance-ready-policies-awsnative
diff --git a/content/docs/iac/crossguard/compliance-ready-policies-azure.md b/content/docs/iac/crossguard/compliance-ready-policies-azure.md
@@ -7,7 +7,7 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
         name: Azure Policies
-        parent: iac-using-pulumi-policy-compliance
+        parent: iac-policy-compliance
         weight: 4
 aliases:
     - /docs/using-pulumi/crossguard/compliance-ready-policies-azure/
diff --git a/content/docs/iac/crossguard/compliance-ready-policies-azurenative.md b/content/docs/iac/crossguard/compliance-ready-policies-azurenative.md
@@ -1,14 +1,14 @@
 ---
-title_tag: "Compliance Ready Policies (Azurenative) | CrossGuard"
-meta_desc: This page contains the list of Compliance Policies for Azurenative.
-title:  Compliance Ready Azurenative Policies
-h1: List of Compliance Ready Policies for Azurenative
+title_tag: "Compliance Ready Policies (Azure Native) | CrossGuard"
+meta_desc: This page contains the list of Compliance Policies for Azure Native.
+title:  Compliance Ready Azure Native Policies
+h1: List of Compliance Ready Policies for Azure Native
 weight: 2
 meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
         name: Azure Native Policies
-        parent: iac-using-pulumi-policy-compliance
+        parent: iac-policy-compliance
         weight: 5
 aliases:
     - /docs/using-pulumi/crossguard/compliance-ready-policies-azurenative/
diff --git a/content/docs/iac/crossguard/compliance-ready-policies-gcp.md b/content/docs/iac/crossguard/compliance-ready-policies-gcp.md
@@ -7,7 +7,7 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
         name: GCP Policies
-        parent: iac-using-pulumi-policy-compliance
+        parent: iac-policy-compliance
         weight: 6
 aliases:
     - /docs/using-pulumi/crossguard/compliance-ready-policies-gcp/
diff --git a/content/docs/iac/crossguard/compliance-ready-policies-googlenative.md b/content/docs/iac/crossguard/compliance-ready-policies-googlenative.md
@@ -7,7 +7,7 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
         name: Google Native Policies
-        parent: iac-using-pulumi-policy-compliance
+        parent: iac-policy-compliance
         weight: 7
 aliases:
     - /docs/using-pulumi/crossguard/compliance-ready-policies-googlenative/
diff --git a/content/docs/iac/crossguard/compliance-ready-policies-kubernetes.md b/content/docs/iac/crossguard/compliance-ready-policies-kubernetes.md
@@ -7,7 +7,7 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
         name: Kubernetes Policies
-        parent: iac-using-pulumi-policy-compliance
+        parent: iac-policy-compliance
         weight: 8
 aliases:
     - /docs/using-pulumi/crossguard/compliance-ready-policies-kubernetes/
diff --git a/content/docs/iac/crossguard/compliance-ready-policies.md b/content/docs/iac/crossguard/compliance-ready-policies.md
@@ -8,9 +8,9 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
         name: Compliance-ready policies
-        parent: iac-using-pulumi-policy
+        parent: iac-policy
         weight: 7
-        identifier: iac-using-pulumi-policy-compliance
+        identifier: iac-policy-compliance
 aliases:
     - /docs/using-pulumi/crossguard/compliance-ready-policies/
     - /docs/iac/packages-and-automation/crossguard/compliance-ready-policies/
diff --git a/content/docs/iac/crossguard/configuration.md b/content/docs/iac/crossguard/configuration.md
@@ -8,7 +8,7 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
         name: Policy configuration
-        parent: iac-using-pulumi-policy
+        parent: iac-policy
         weight: 4
 aliases:
 - /docs/guides/crossguard/configuration/
diff --git a/content/docs/iac/crossguard/core-concepts.md b/content/docs/iac/crossguard/core-concepts.md
@@ -9,9 +9,9 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
         name: Concepts
-        parent: iac-using-pulumi-policy
+        parent: iac-policy
         weight: 2
-        identifier: iac-using-pulumi-policy-concepts
+        identifier: iac-policy-concepts
 aliases:
 - /docs/guides/crossguard/core-concepts/
 - /docs/using-pulumi/crossguard/core-concepts/
diff --git a/content/docs/iac/crossguard/faq.md b/content/docs/iac/crossguard/faq.md
@@ -8,9 +8,9 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
         name: FAQ
-        parent: iac-using-pulumi-policy
+        parent: iac-policy
         weight: 8
-        identifier: iac-using-pulumi-policy-faq
+        identifier: iac-policy-faq
 aliases:
 - /docs/guides/crossguard/faq/
 - /docs/using-pulumi/crossguard/faq/
diff --git a/content/docs/iac/crossguard/get-started.md b/content/docs/iac/crossguard/get-started.md
@@ -9,7 +9,7 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
         name: Get started
-        parent: iac-using-pulumi-policy
+        parent: iac-policy
         weight: 1
 aliases:
 - /docs/get-started/policy-as-code
diff --git a/content/docs/iac/crossguard/policy-violations.md b/content/docs/iac/crossguard/policy-violations.md
@@ -8,7 +8,7 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
         name: Policy violations
-        parent: iac-using-pulumi-policy
+        parent: iac-policy
         weight: 3
 aliases:
     - /docs/using-pulumi/crossguard/policy-violations/
diff --git a/content/docs/iac/crossguard/snyk-policy.md b/content/docs/iac/crossguard/snyk-policy.md
@@ -8,7 +8,7 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
         name: Snyk container scanning
-        parent: iac-using-pulumi-policy
+        parent: iac-policy
         weight: 6
 aliases:
 - /docs/guides/crossguard/snyk-container-scanning/
diff --git a/content/docs/iac/extending-pulumi/_index.md b/content/docs/iac/extending-pulumi/_index.md
@@ -7,8 +7,8 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
         name: Extending Pulumi
-        parent: iac-using-pulumi
-        weight: 4
+        parent: iac-home
+        weight: 76
         identifier: iac-extending-pulumi
 ---
 
diff --git a/content/docs/iac/extending-pulumi/build-a-provider.md b/content/docs/iac/extending-pulumi/build-a-provider.md
diff --git a/content/docs/iac/extending-pulumi/debugging-providers.md b/content/docs/iac/extending-pulumi/debugging-providers.md
diff --git a/content/docs/iac/extending-pulumi/img/goland-debug-config.png b/content/docs/iac/extending-pulumi/img/goland-debug-config.png
diff --git a/content/docs/iac/extending-pulumi/img/vscode-debug-config-connect-to-server.png b/content/docs/iac/extending-pulumi/img/vscode-debug-config-connect-to-server.png
diff --git a/content/docs/iac/extending-pulumi/img/vscode-debug-config.png b/content/docs/iac/extending-pulumi/img/vscode-debug-config.png
diff --git a/content/docs/iac/extending-pulumi/img/vscode-launch-config-connect-to-server.png b/content/docs/iac/extending-pulumi/img/vscode-launch-config-connect-to-server.png
diff --git a/content/docs/iac/extending-pulumi/img/vscode-launch-config.png b/content/docs/iac/extending-pulumi/img/vscode-launch-config.png
diff --git a/content/docs/iac/extending-pulumi/publishing-packages.md b/content/docs/iac/extending-pulumi/publishing-packages.md
diff --git a/content/docs/iac/extending-pulumi/pulumi-provider-sdk.md b/content/docs/iac/extending-pulumi/pulumi-provider-sdk.md
diff --git a/content/docs/iac/extending-pulumi/schema.md b/content/docs/iac/extending-pulumi/schema.md
diff --git a/content/docs/iac/extending-pulumi/use-terraform-module.md b/content/docs/iac/extending-pulumi/use-terraform-module.md
diff --git a/content/docs/iac/using-pulumi/_index.md b/content/docs/iac/using-pulumi/_index.md
@@ -8,23 +8,19 @@ menu:
     iac:
         name: Using Pulumi
         parent: iac-home
-        weight: 50
+        weight: 65
         identifier: iac-using-pulumi
 aliases:
 - /docs/guides/
 - /docs/using-pulumi/
 - /docs/iac/packages-and-automation/
 ---
 
-Learn how to adopt Pulumi, organize projects & stacks, use the Automation API, continuous delivery, policy as code, pulumi packages, and test Pulumi code.
+Learn best practices to use Pulumi.
 
-## General Guides
+## Guides
 
-- [Adopting Pulumi](/docs/iac/adopting-pulumi/)
-- [Organizing projects & stacks](/docs/iac/packages-and-automation/organizing-projects-stacks/)
-- [Automation API](/docs/iac/packages-and-automation/automation-api/)
-- [Continuous delivery](/docs/iac/packages-and-automation/continuous-delivery/)
-- [Policy as code](/docs/iac/packages-and-automation/crossguard/)
-- [Pulumi packages](/docs/iac/packages-and-automation/pulumi-packages/)
-- [Testing](/docs/iac/concepts/testing/)
-- [Debugging](/docs/iac/concepts/debugging/)
+- [Organizing projects & stacks](/docs/iac/using-pulumi/organizing-projects-stacks/)
+- [Least privilege security](/docs/iac/using-pulumi/iac-least-privileges/)
+- [Build a Component](/docs/iac/using-pulumi/build-a-component/)
+- [Pulumi and Continuous delivery](/docs/iac/using-pulumi/continuous-delivery/)
diff --git a/content/docs/iac/using-pulumi/build-a-component.md b/content/docs/iac/using-pulumi/build-a-component.md
@@ -7,8 +7,8 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
         name: Build a Component
-        parent: iac-extending-pulumi
-        weight: 1
+        parent: iac-using-pulumi
+        weight: 6
 ---
 
 This guide will walk you through the steps of making a Pulumi Component suitable for reuse in all languages and cloud environments.
diff --git a/content/topics/kubernetes.md b/content/topics/kubernetes.md
@@ -255,7 +255,7 @@ superpowers:
 
     - title: Be Proactive, Not Reactive
       cta: Learn more
-      cta_url: "/docs/iac/using-pulumi/crossguard/"
+      cta_url: "/docs/iac/crossguard/"
       icon_type: shield
       icon_color: yellow
       description: |
diff --git a/layouts/page/automation.html b/layouts/page/automation.html
@@ -31,7 +31,7 @@ <h3>Harness the full power of Infrastructure as Code</h3>
                     you to build custom cloud interfaces that are tailored to your team, organization, or customers.
                 </p>
                 <div class="my-8">
-                    <a class="btn-primary" href="{{ relref . "/docs/iac/using-pulumi/automation-api/" }}">Learn More</a>
+                    <a class="btn-primary" href="{{ relref . "/docs/iac/automation-api/" }}">Learn More</a>
                 </div>
             </div>
         </div>
@@ -431,7 +431,7 @@ <h4>Workshop</h4>
             <h2 class="text-white">Get started today</h2>
             <p class="text-white">To get started with Pulumi Automation API, visit the user guide in our documentation.</p>
             <div class="mt-16">
-                <a class="btn-secondary" href="{{ relref . "/docs/iac/using-pulumi/automation-api/getting-started-automation-api/" }}">View the Guide</a>
+                <a class="btn-secondary" href="{{ relref . "/docs/iac/automation-api/getting-started-automation-api/" }}">View the Guide</a>
             </div>
         </div>
     </section>
diff --git a/layouts/page/product-packages.html b/layouts/page/product-packages.html
@@ -149,7 +149,7 @@ <h4 class="text-white">{{ .Params.get_started.browse.title }}</h4>
                     <div class="border lg:border-none lg:shadow-2xl p-8 lg:px-12 lg:pt-4 g:pb-12 rounded-xl bg-white h-full">
                         <h4>{{ .Params.get_started.publish.title }}</h4>
                         <p class="mb-12">{{ .Params.get_started.publish.description }}</p>
-                        <a href="{{ relref . "/docs/iac/using-pulumi/extending-pulumi/" }}" class="btn-secondary"
+                        <a href="{{ relref . "/docs/iac/extending-pulumi/" }}" class="btn-secondary"
                             >{{ .Params.get_started.publish.cta_text }}</a
                         >
                     </div>
