Skip to content

Enhance documentation structure for Pulumi ESC getting started guides #16533

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
wants to merge 7 commits into
base: master
Choose a base branch
from
Draft

Enhance documentation structure for Pulumi ESC getting started guides #16533

wants to merge 7 commits into from
+1,347 −628

Conversation

@CamSoper
Copy link
Contributor

@CamSoper CamSoper commented Nov 10, 2025 •
edited
Loading

This PR restructures the Pulumi ESC documentation to improve discoverability and user experience.

Key Changes

Getting Started:

  • Replaced 8-page tutorial with a single 5-minute quick start
  • Focused on essential first steps: create environment, add secret via web UI, retrieve via CLI
  • Added strong call-to-action directing users to IaC integration guide

New Guides Section:

  • Created dedicated /docs/esc/guides/ with 6 self-contained guides:
    • Integrate with Pulumi IaC
    • Managing secrets
    • Running commands with ESC
    • Setting up OIDC
    • Importing environments
    • External secrets integration

Concepts Enhancement:

  • Expanded concepts/_index.md with structured explanations of core concepts
  • Improved organization around environments, sources, targets, and management

Navigation & SEO:

  • Updated menu weights for better navigation flow (Guides before Environments)
  • All aliases properly configured to preserve search rankings and external links
  • Git history preserved via git mv for moved content

Link Fixes:

  • Fixed broken anchor links in external-secrets.md
  • Updated internal documentation links to point to new guide locations

Fixes #15784

@claude
Copy link
Contributor

claude bot commented Nov 10, 2025

Documentation Review

I've reviewed PR #16533 which enhances the Pulumi ESC getting started guide structure. Overall, this is a well-executed documentation improvement that makes it easier for users to navigate based on their familiarity with Pulumi. Below are my findings:

Issues Found

1. Missing article in heading (content/docs/esc/get-started/_index.md:32)

Location: content/docs/esc/get-started/_index.md, line 32

Issue: The heading "Choose your path" should include the article "the" for proper grammar.

Suggestion:

## Choose your path

Should be:

## Choose the right path

Or alternatively:

## Choose your learning path

2. Incomplete sentence structure (content/docs/esc/get-started/integrate-with-pulumi-iac.md:78)

Location: content/docs/esc/get-started/integrate-with-pulumi-iac.md, line 78

Issue: The sentence "Share AWS OIDC credentials across multiple stacks:" uses a colon to introduce a code block, but the context could be clearer. Consider rewording for better flow.

Current:

Share AWS OIDC credentials across multiple stacks:

Suggested:

To share AWS OIDC credentials across multiple stacks, configure your ESC environment like this:

3. Inconsistent section header capitalization (content/docs/esc/get-started/integrate-with-pulumi-iac.md:42)

Location: content/docs/esc/get-started/integrate-with-pulumi-iac.md, line 42

Issue: "pulumiConfig" in the explanatory text should be formatted as code since it's a YAML key.

Current:

The `pulumiConfig` block maps ESC values to Pulumi configuration keys.

This is actually correct - good job using code formatting! No change needed.

Positive Observations

  1. Clear user segmentation - The new "Choose your path" section effectively guides users based on their experience level
  2. Restructured flow - Moving "Integrate with Pulumi IaC" earlier (weight 4) makes sense for existing Pulumi users
  3. Practical examples - The new examples section provides concrete, real-world use cases
  4. Simplified content - Removing the lengthy tutorial walkthrough in favor of a quick 3-step integration guide is more practical
  5. Good use of shortcodes - Proper use of the notes shortcode with appropriate type
  6. Proper formatting - Code blocks are correctly fenced with appropriate language identifiers

Content Accuracy

  • All YAML examples appear syntactically correct
  • Configuration API usage examples are consistent with Pulumi's patterns
  • Links to other getting started pages are properly formatted
  • The weight changes (4, 5, 6, 7, 8) maintain proper ordering without gaps

Style Compliance

  • Headings follow proper sentence case (H2+)
  • Lists use proper formatting
  • Code blocks use fenced code blocks, not indentation
  • Links are descriptive
  • Paragraphs are appropriately sized

Recommendation

The PR is in good shape. The two issues noted above are minor and don't block merging, but would improve the documentation quality if addressed.

Mention @claude if you'd like me to review additional changes or help with fixes.

@pulumi-bot
Copy link
Collaborator

pulumi-bot commented Nov 10, 2025

Your site preview for commit 13344f3 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16533-13344f39.s3-website.us-west-2.amazonaws.com.

@pulumi-bot
Copy link
Collaborator

pulumi-bot commented Nov 11, 2025

Your site preview for commit 3950013 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16533-3950013c.s3-website.us-west-2.amazonaws.com.

@pulumi-bot
Copy link
Collaborator

pulumi-bot commented Nov 11, 2025

Your site preview for commit 6f7f4e3 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16533-6f7f4e3a.s3-website.us-west-2.amazonaws.com.

@CamSoper
Add guides for Pulumi ESC, including managing secrets, integrating wi…
c4e9c68 
…th Pulumi IaC, and setting up OIDC

- Introduced new "Get Started"
- Created a new index page for guides on Pulumi ESC.
- Added detailed guides for integrating external secrets from AWS, Azure, and GCP.
- Introduced a guide on importing environments to share configuration across teams.
- Developed a guide on managing secrets, including storing and retrieving them.
- Added instructions for running commands with `esc run` to inject secrets into scripts.
- Created a guide for setting up OIDC to generate dynamic cloud credentials.
- Updated references in existing documentation to point to new guides.
@pulumi-bot
Copy link
Collaborator

pulumi-bot commented Nov 11, 2025

Your site preview for commit c4e9c68 is ready! 🎉

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

@pulumi-bot
Copy link
Collaborator

pulumi-bot commented Nov 12, 2025

Your site preview for commit 7b45727 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16533-7b457276.s3-website.us-west-2.amazonaws.com.

@CamSoper
Add script to add borders to PNG images in markdown files
8e964bf 
- Created a new script `add_borders.py` that adds 1px #CCCCCC borders to PNG images referenced in markdown files.
- Implemented functionality to check for existing borders and avoid duplication.
- Added metadata to processed images to track border addition.
- Included a `Pipfile` for dependency management, requiring `pillow` and `click`.
- Added command-line interface for user interaction, supporting dry-run mode.
@pulumi-bot
Copy link
Collaborator

pulumi-bot commented Nov 14, 2025

Your site preview for commit 8e964bf is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16533-8e964bf0.s3-website.us-west-2.amazonaws.com.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Improve Pulumi ESC Getting Started

3 participants

@CamSoper @pulumi-bot