Fix markdown indentation issues and add detection scripts (#16429)

* Fix indentation issues in markdown files and add scripts for detection and correction

* Add guidelines for checking indentation and clarify style guide scope

Author: CamSoper

.claude/commands/docs-review.md

@@ -90,6 +90,7 @@ Always provide relevant line numbers for any issues you identify.
 - Confirm that **all links resolve** and point to the correct targets (no 404s, no mislinked paths).
 - Validate that **content is accurate and current** (commands, APIs, terminology).
 - Ensure **all new files end with a newline**.
+- Double-check indented lines to ensure they are not incorrectly indented as code blocks.
 - **Code examples** must run correctly and follow best practices:
   - Do not suggest untested code.
   - Examples should show realistic use cases, not contrived demos.

STYLE-GUIDE.md

@@ -5,6 +5,17 @@ For topics not addressed here, refer to the [Google Developer Documentation Styl
 
 ---
 
+## Scope
+
+This style guide applies to all Hugo content files in this repository.
+
+The following exceptions are specifically excluded from this style guide:
+
+- Non-content files (scripts, configuration, etc.) should follow general best practices for that file type.
+- Meta Markdown files (e.g., `README.md`, `AGENTS.md`) may use different conventions as appropriate.
+
+---
+
 ## Inclusive Language
 
 Pulumi strives to use language that is clear, inclusive, and respectful.  

content/docs/iac/get-started/aws/next-steps.md

@@ -19,11 +19,11 @@ aliases:
 
 Congratulations! You've successfully provisioned some cloud resources using Pulumi. By completing this guide you have successfully:
 
-    - Created a Pulumi new project.
-    - Provisioned a new S3 bucket.
-    - Turned it into a static website.
-    - Created a website component for easy reuse.
-    - Destroyed all of the resources you've provisioned.
+- Created a Pulumi new project.
+- Provisioned a new S3 bucket.
+- Turned it into a static website.
+- Created a website component for easy reuse.
+- Destroyed all of the resources you've provisioned.
 
 Below are some recommended next steps, including examples and tutorials that you can explore or use them as a foundation for your own applications and infrastructure projects. Also be sure to [join the Community Slack](https://slack.pulumi.com/) to meet fellow IaC practitioners.
 

content/docs/iac/get-started/azure/destroy-stack.md

@@ -67,11 +67,11 @@ entirely from Pulumi Cloud, along with all of its update history.
 
 Congratulations! You've successfully provisioned some cloud resources using Pulumi. By completing this guide you have successfully:
 
-    - Created a Pulumi new project.
-    - Provisioned a new Azure storage account and container.
-    - Added an `index.html` file to your container.
-    - Served the `index.html` as a static website.
-    - Destroyed the resources you've provisioned.
+- Created a Pulumi new project.
+- Provisioned a new Azure storage account and container.
+- Added an `index.html` file to your container.
+- Served the `index.html` as a static website.
+- Destroyed the resources you've provisioned.
 
 On the next page, we have a collection of examples and tutorials that you can deploy as they are or use them as a foundation for your own applications and infrastructure projects.
 

content/docs/iac/get-started/azure/next-steps.md

@@ -24,9 +24,9 @@ Congrats! You've deployed your first project on Microsoft Azure with Pulumi. Her
 
 With Pulumi ESC you can:
 
-    - **Stop secret sprawl.** Pull and sync configuration and secrets with any secrets store – including HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, 1Password, and more – and consume in any application, tool, or CI/CD platform.
-    - **Trust (and prove) your secrets are secure.** Every environment can be locked down with role-based access controls (RBAC) and versioned with all changes fully logged for auditing.
-    - **Ditch `.env` files.** No more storing secrets in plaintext on dev computers. Developers can easily access secrets via CLI, API, Kubernetes operator, the Pulumi Cloud UI, and in-code with Typescript/Javascript, Python, and Go SDKs.
+- **Stop secret sprawl.** Pull and sync configuration and secrets with any secrets store – including HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, 1Password, and more – and consume in any application, tool, or CI/CD platform.
+- **Trust (and prove) your secrets are secure.** Every environment can be locked down with role-based access controls (RBAC) and versioned with all changes fully logged for auditing.
+- **Ditch `.env` files.** No more storing secrets in plaintext on dev computers. Developers can easily access secrets via CLI, API, Kubernetes operator, the Pulumi Cloud UI, and in-code with Typescript/Javascript, Python, and Go SDKs.
 
 {{< get-started-next-step path="/docs/esc/get-started/" label="Learn more about Pulumi ESC" ref="gs-azure-esc" >}}
 

content/docs/iac/get-started/gcp/destroy-stack.md

@@ -65,11 +65,11 @@ Optionally, to delete the stack itself, you can also run [`pulumi stack rm`](/do
 
 Congratulations! You've successfully provisioned some cloud resources using Pulumi. By completing this guide you have successfully:
 
-    - Created a Pulumi new project.
-    - Provisioned a new storage bucket.
-    - Added an `index.html` file to your bucket.
-    - Served the file as a static website.
-    - Destroyed the resources you've provisioned.
+- Created a Pulumi new project.
+- Provisioned a new storage bucket.
+- Added an `index.html` file to your bucket.
+- Served the file as a static website.
+- Destroyed the resources you've provisioned.
 
 On the next page, we have a collection of examples and tutorials that you can deploy as they are or use them as a foundation for your own applications and infrastructure projects.
 

content/docs/iac/get-started/gcp/next-steps.md

@@ -25,9 +25,9 @@ Congrats! You've deployed your first project on Google Cloud with Pulumi. Here a
 
 With Pulumi ESC you can:
 
-    - **Stop secret sprawl.** Pull and sync configuration and secrets with any secrets store – including HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, 1Password, and more – and consume in any application, tool, or CI/CD platform.
-    - **Trust (and prove) your secrets are secure.** Every environment can be locked down with role-based access controls (RBAC) and versioned with all changes fully logged for auditing.
-    - **Ditch `.env` files.** No more storing secrets in plaintext on dev computers. Developers can easily access secrets via CLI, API, Kubernetes operator, the Pulumi Cloud UI, and in-code with Typescript/Javascript, Python, and Go SDKs.
+- **Stop secret sprawl.** Pull and sync configuration and secrets with any secrets store – including HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, 1Password, and more – and consume in any application, tool, or CI/CD platform.
+- **Trust (and prove) your secrets are secure.** Every environment can be locked down with role-based access controls (RBAC) and versioned with all changes fully logged for auditing.
+- **Ditch `.env` files.** No more storing secrets in plaintext on dev computers. Developers can easily access secrets via CLI, API, Kubernetes operator, the Pulumi Cloud UI, and in-code with Typescript/Javascript, Python, and Go SDKs.
 
 {{< get-started-next-step path="/docs/esc/get-started" label="Learn more about Pulumi ESC" ref="gs-gcp-esc" >}}
 

scripts/indent-fixes/README.md

@@ -0,0 +1,172 @@
+# Indent Fixes Scripts
+
+These scripts detect and fix incorrectly indented bullet lists in markdown files. This issue occurred during the content reorganization (PRs #16119, #16303) where bullet lists were inadvertently indented with 4 spaces, causing Hugo to render them as code blocks instead of proper lists.
+
+## The Problem
+
+In markdown, 4 spaces of indentation before a bullet point creates a code block instead of a list item:
+
+```markdown
+<!-- WRONG: Renders as code block -->
+    - This is a bullet point
+    - Another bullet point
+
+<!-- CORRECT: Renders as list -->
+- This is a bullet point
+- Another bullet point
+```
+
+During the content reorganization, some bullet lists were accidentally indented with 4 spaces, breaking their rendering on the website.
+
+## Usage
+
+### Quick Start
+
+From the repository root:
+
+```bash
+cd scripts/indent-fixes
+
+# Step 1: Detect issues
+python3 detect_indent_issues.py
+
+# Step 2: Review the report, then fix all issues
+python3 fix_indent_issues.py
+
+# Step 3: Verify the changes
+git diff content/docs/
+```
+
+### Step 1: Detection
+
+Run the detection script to find all problematic indentations:
+
+```bash
+python3 detect_indent_issues.py
+```
+
+This will output:
+- Summary count of files with issues
+- Line-by-line listing of each problematic indentation
+- Total count of issues found
+
+**Example output:**
+```
+Found 14 files with potential indentation issues:
+
+content/docs/iac/get-started/aws/next-steps.md: 5 issue(s)
+  Line 22:     - Created a Pulumi new project.
+  Line 23:     - Provisioned a new S3 bucket.
+  Line 24:     - Turned it into a static website.
+  Line 25:     - Created a website component for easy reuse.
+  Line 26:     - Destroyed all of the resources you've provisioned.
+
+Total: 66 potential issues across 14 files
+```
+
+### Step 2: Fix Issues
+
+After reviewing the detection report, run the fix script:
+
+```bash
+python3 fix_indent_issues.py
+```
+
+This will:
+- Process all markdown files in `content/docs/`
+- Remove 4-space indentation from incorrectly indented bullet points
+- Report the number of lines fixed per file
+
+**Example output:**
+```
+Fixed 66 lines across 14 files:
+
+  content/docs/iac/get-started/aws/next-steps.md: 5 line(s) fixed
+  content/docs/iac/get-started/azure/destroy-stack.md: 5 line(s) fixed
+  content/docs/iac/get-started/azure/next-steps.md: 3 line(s) fixed
+  ...
+```
+
+### Step 3: Verify Changes
+
+Review the changes made by the script:
+
+```bash
+# View summary of changes
+git diff --stat content/docs/
+
+# View detailed changes
+git diff content/docs/
+
+# Test the build
+make build
+```
+
+## How It Works
+
+### Detection Logic
+
+The `detect_indent_issues.py` script intelligently identifies problematic indentations while avoiding false positives:
+
+**What it detects:**
+- Lines matching the pattern `^    - ` (4 spaces + dash + space)
+- In markdown content sections (not frontmatter or code blocks)
+
+**What it excludes:**
+- **YAML frontmatter**: Indentation between `---` markers is correct YAML syntax
+- **Code blocks**: Content within ` ``` ` fences is left untouched
+- **Nested lists**: Legitimate 2nd-level list items (preceded by 2-space indented parent)
+- **YAML-like structures**: Content that looks like YAML configuration blocks
+
+### Fix Logic
+
+The `fix_indent_issues.py` script:
+
+1. Uses the same detection logic to identify problematic lines
+2. Removes exactly 4 spaces from the beginning of each line
+3. Writes the corrected content back to the file
+4. Reports the number of changes made
+
+**Safety features:**
+- Only modifies lines that match the detection criteria
+- Preserves all other formatting (newlines, trailing spaces, etc.)
+- Non-destructive: Can be reviewed with `git diff` before committing
+
+## When to Use These Scripts
+
+- **After content reorganizations**: When files are moved/renamed, indentation issues may be introduced
+- **When rendering issues occur**: If bullet lists appear as code blocks on the site
+- **Periodic audits**: Run detection periodically to catch any new issues
+
+## Workflow
+
+1. Make content changes or complete a reorganization
+2. Run `python3 detect_indent_issues.py` to check for issues
+3. Review the detection report
+4. Run `python3 fix_indent_issues.py` to apply fixes
+5. **IMPORTANT** -- Review changes with `git diff`! There *will* be false positives!
+6. Run `make build` to verify the site builds correctly
+7. Commit the fixes
+
+## Exit Codes
+
+Both scripts return:
+- **0** - Success (issues found and reported, or no issues found)
+- **Non-zero** - Unexpected error occurred
+
+## Related
+
+- See `scripts/alias-verification/` for tools to verify file move aliases
+- See `STYLE-GUIDE.md` for markdown formatting guidelines
+
+## History
+
+These scripts were created to fix issues introduced during:
+- PR #16119: Major documentation reorganization
+- PR #16303: Insights & Governance docs reorganization
+
+The fixes were partially addressed in:
+- PR #16427: Fixed get-started guides
+- PR #16428: Fixed next-steps pages
+
+This toolset completes the remediation and provides ongoing verification.

scripts/indent-fixes/detect_indent_issues.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""
+Detect incorrectly indented bullet points in markdown files.
+This script finds bullet lists with 4-space indentation that should be unindented.
+It distinguishes between YAML frontmatter (where indentation is correct) and
+markdown content (where 4-space indentation creates code blocks).
+"""
+
+import re
+from pathlib import Path
+from typing import List, Tuple
+
+def detect_indent_issues(file_path: str) -> List[Tuple[int, str]]:
+    """
+    Detect lines with problematic 4-space indentation before bullet points.
+    Returns a list of (line_number, line_content) tuples.
+    """
+    issues = []
+
+    with open(file_path, 'r', encoding='utf-8') as f:
+        lines = f.readlines()
+
+    in_frontmatter = False
+    frontmatter_count = 0
+    in_code_block = False
+
+    for i, line in enumerate(lines, 1):
+        # Track frontmatter boundaries (YAML between --- markers)
+        if line.strip() == '---':
+            frontmatter_count += 1
+            if frontmatter_count == 1:
+                in_frontmatter = True
+            elif frontmatter_count == 2:
+                in_frontmatter = False
+            continue
+
+        # Track code blocks (```)
+        if line.strip().startswith('```'):
+            in_code_block = not in_code_block
+            continue
+
+        # Skip if we're in frontmatter or code block
+        if in_frontmatter or in_code_block:
+            continue
+
+        # Check for 4-space indented bullet points
+        # Pattern: exactly 4 spaces, then dash, then space or content
+        if re.match(r'^    - ', line):
+            # Check if this might be a legitimate nested list item
+            # Look at previous lines to see if there's a parent list item
+            is_nested = False
+            if i > 1:
+                # Check previous non-empty lines
+                for j in range(i-2, max(0, i-10), -1):
+                    prev_line = lines[j].rstrip()
+                    if not prev_line:
+                        continue
+                    # If previous line is a list item without indent, this might be nested
+                    if re.match(r'^  - ', prev_line):
+                        is_nested = True
+                        break
+                    # If we hit another non-list line, assume not nested
+                    if prev_line and not prev_line.startswith(' '):
+                        break
+
+            # Also check for YAML-like context (key: value patterns nearby)
+            is_yaml_context = False
+            if i > 1 and i < len(lines):
+                # Check surrounding lines for YAML patterns
+                for j in range(max(0, i-5), min(len(lines), i+5)):
+                    if re.search(r'^\w+:', lines[j]):
+                        # Could be YAML or markdown heading
+                        # If it's followed by indented content, likely YAML
+                        if j < len(lines) - 1 and lines[j+1].startswith('  '):
+                            is_yaml_context = True
+                            break
+
+            if not is_nested and not is_yaml_context:
+                issues.append((i, line.rstrip()))
+
+    return issues
+
+def main():
+    # Search in content/docs directory (relative to repo root)
+    # Script can be run from repo root or from scripts/indent-fixes/
+    repo_root = Path(__file__).parent.parent.parent
+    content_dir = repo_root / 'content' / 'docs'
+
+    all_issues = {}
+
+    for md_file in content_dir.rglob('*.md'):
+        issues = detect_indent_issues(str(md_file))
+        if issues:
+            all_issues[str(md_file)] = issues
+
+    # Print results
+    if all_issues:
+        print(f"Found {len(all_issues)} files with potential indentation issues:\n")
+        total_issues = 0
+        for file_path in sorted(all_issues.keys()):
+            issues = all_issues[file_path]
+            total_issues += len(issues)
+            print(f"\n{file_path}: {len(issues)} issue(s)")
+            for line_num, line_content in issues:
+                print(f"  Line {line_num}: {line_content}")
+
+        print(f"\n\nTotal: {total_issues} potential issues across {len(all_issues)} files")
+    else:
+        print("No indentation issues found.")
+
+if __name__ == '__main__':
+    main()