Update documentation to include nested stacks recommended tree layout

[LuisaoStuff]

Description

This PR improves the Stacks documentation by clarifying best practices for structuring explicit Terragrunt stacks, especially in reusable catalog setups. It adds guidance on:

• How to correctly structure reusable catalog stacks and live stacks.
• How to pass config_path values through stack blocks so that dependency blocks are only declared inside units, avoiding parsing errors.
• Recommended use of ${get_repo_root()} to define stable and predictable paths across environments.
• Expanded examples showing a “catalog main stack” pattern that can be reused by multiple environments.

These changes aim to reduce confusion around nested explicit stacks, improve reproducibility, and prevent common pitfalls encountered by users implementing multi-environment catalogs.

TODOs

Read the Gruntwork contribution guidelines.

• I authored this code entirely myself
• I am submitting code based on open source software (e.g. MIT, MPL-2.0, Apache)]
• I am adding or upgrading a dependency or adapted code and confirm it has a compatible open source license
• Update the docs.
• Run the relevant tests successfully, including pre-commit checks.
• Include release notes. If this PR is backward incompatible, include a migration guide.

Summary by CodeRabbit

• Documentation
  • Added extensive documentation on stack configuration with recommended patterns for catalog main stack architecture and reusable stacks. Includes detailed file-tree layouts, HCL code examples, best practices for environment-specific values, nested stacks, dependency management, explicit stack structures, generation workflows, and guidance for achieving robust and reproducible deployments across multiple environments.

[vercel]

Someone is attempting to deploy a commit to the Gruntwork Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds a comprehensive documentation section to the stacks guide covering a recommended catalog/main stack pattern, including detailed file structures, HCL examples for environment stacks, patterns for explicit stacks, dependency wiring guidelines, and common deployment workflows for multi-level configurations.

Changes

Cohort / File(s)	Summary
Documentation: Stacks feature guide expansion docs-starlight/src/content/docs/03-features/02-stacks.mdx	Adds new "Recommended layout with a reusable catalog main stack" section with file-tree layouts, HCL code examples (catalog main stacks, live environment stacks), patterns for explicit stacks, dependency wiring guidelines across multiple stack levels, and workflows for stack generation and deployment.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~8 minutes

• Considerations: Documentation-only changes with no code logic, API modifications, or structural updates. Review focuses on content accuracy, clarity, code example correctness, and consistency with existing documentation patterns.

Possibly related PRs

• docs: Updating stacks documentation #4544: Expands documentation explaining explicit/implicit stack patterns and usage, complementing this PR's catalog/main stack layout guidance.
• docs: Updating docs now that stacks are generally available #4243: Modifies stacks documentation with stack-related commands and examples, related to this PR's recommended layout additions.
• docs: Add Terralith to Terragrunt guide #4709: Modifies the same stacks documentation file with minor language refinements in fenced code blocks.

Suggested reviewers

• denis256
• yhakbar
• levkohimins

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Update documentation to include nested stacks recommended tree layout' directly reflects the main change: adding comprehensive documentation on nested stacks with recommended structural patterns.
Description check	✅ Passed	The PR description addresses the required template sections adequately, clearly explaining the changes, checking relevant TODOs, and confirming documentation updates and testing.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

Tip

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

• Provide your own instructions using the high_level_summary_instructions setting.
• Format the summary however you like (bullet lists, tables, multi-section layouts, contributor stats, etc.).
• Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example instruction:

"Divide the high-level summary into five sections:

1. 📝 Description — Summarize the main change in 50–60 words, explaining what was done.
2. 📓 References — List relevant issues, discussions, documentation, or related PRs.
3. 📦 Dependencies & Requirements — Mention any new/updated dependencies, environment variable changes, or configuration updates.
4. 📊 Contributor Summary — Include a Markdown table showing contributions:
   | Contributor | Lines Added | Lines Removed | Files Changed |
5. ✔️ Additional Notes — Add any extra reviewer context.
   Keep each section concise (under 200 words) and use bullet or numbered lists for clarity."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

docs-starlight/src/content/docs/03-features/02-stacks.mdx (2)

281-281: Consider strengthening the adjective at line 281.

The phrase "is very small" uses a weak intensifier. Consider alternatives like "is minimal," "is concise," or simply "contains just" to make the description more direct.

---

468-474: Reduce repetitive sentence structure in the bulleted list.

Five consecutive bullet points begin with "It," which creates monotonous pacing. Consider varying the sentence structure—for example:

-* It keeps catalog stacks declarative, focusing on *structure*.
-* It ensures unit files remain the only place where runtime dependencies are evaluated.
-* It avoids the "unsupported block `dependency` in stack" errors.
-* It enables nested stacks to pass dependency paths cleanly through recursive `values`.
-* It keeps the stack generate mechanism stable even in large multi–environment catalogs.
+* Catalog stacks remain declarative, focusing on *structure*.
+* Unit files become the only place where runtime dependencies are evaluated.
+* This pattern avoids the "unsupported block `dependency` in stack" errors.
+* Nested stacks can pass dependency paths cleanly through recursive `values`.
+* The stack generate mechanism stays stable even in large multi–environment catalogs.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between bfcf295 and 47310df.

📒 Files selected for processing (1)

• docs-starlight/src/content/docs/03-features/02-stacks.mdx (1 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

docs-starlight/**/*.md*

⚙️ CodeRabbit configuration file

docs-starlight/**/*.md*: Review the documentation for clarity, grammar, and spelling. Make sure that the documentation is easy to understand and follow. There is currently a migration underway from the Jekyll based documentation in docs to the Starlight + Astro based documentation in docs-starlight. Make sure that the docs-starlight documentation is accurate and up-to-date with the docs documentation, and that any difference between them results in an improvement in the docs-starlight documentation.

Referenced Documentation Contents

docs-starlight/src/content/docs/03-features/02-stacks.mdx:
Actionable guidelines from the Stacks docs relevant to nested/exlicit stacks:

• Promote a reusable catalog main stack pattern and per-environment live stacks; catalog/main wires sub-stacks (environment, compute, storage) while live environments instantiate the catalog main stack.
• Use get_repo_root() to construct stable, environment-agnostic paths for both catalog stacks and nested stacks; prefer paths like ${get_repo_root()}/catalog/units/... and ${get_repo_root()}/catalog/stacks/...
• Pass dependency/config_path information through values in catalog stacks (e.g., vpc_config_path) instead of declaring dependency blocks inside stack blueprints; declare actual dependency blocks only in generated unit terragrunt.hcl files.
• Do not place dependency blocks inside terragrunt.stack.hcl; keep stack blueprints declarative and focused on structure.
• Inside units, declare dependency blocks using paths provided via values (config_path), and read outputs from dependency.outputs for inputs.
• Use the catalog main stack to compose environment, compute, and storage patterns; live stacks merely provide environment-specific values (environment, cidr, tags, region, etc.).
• Leverage stack generate/run commands to automate creation and deployment of generated units; understand the recommended workflow: generate from stack.hcl, then run apply, or combine as stack run apply.
  ...

Files:

• docs-starlight/src/content/docs/03-features/02-stacks.mdx

🪛 LanguageTool

docs-starlight/src/content/docs/03-features/02-stacks.mdx

[style] ~281-~281: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...*live/<env>/terragrunt.stack.hcl** is very small: it just calls the catalog main stack o...

(EN_WEAK_ADJECTIVE)

---

[style] ~472-~472: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...e runtime dependencies are evaluated. * It avoids the “unsupported block `dependen...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

---

[style] ~473-~473: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... block dependency in stack” errors. * It enables nested stacks to pass dependenc...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

---

[style] ~474-~474: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...s cleanly through recursive values. * It keeps the stack generate mechanism stab...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

🔇 Additional comments (1)

docs-starlight/src/content/docs/03-features/02-stacks.mdx (1)

237-484: Comprehensive addition that aligns well with recommended patterns and guidelines.

This new section effectively introduces the reusable catalog main stack pattern and provides clear guidance on best practices for explicit stacks. The content is well-organized, progresses logically, and includes multiple practical examples that demonstrate the recommended patterns. Particularly strong are the sections on:

• The three-tier stack architecture (catalog main → environment/compute/storage → units)
• Use of get_repo_root() for predictable paths
• Passing config_path through values instead of embedding dependency blocks in stack blueprints

The examples are concrete, would work as written, and effectively illustrate each concept.