docs: update the quickstart guide with additional steps and ToC

[jyecusch]

Fixes NIT-355

Submitting as a draft until the final input variable design for the GCP Platform is finalised, then we can update that last section and publish.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds the term uv to the Suga Vale vocabulary accept list and refactors docs/quickstart.mdx into a sectioned, provider-agnostic Quickstart. The quickstart rewrite replaces step sequences with Markdown sections and info blocks, introduces language tabs (Node.js, Python, Go), expands local development and template guidance, and reorganizes Terraform/provider credential instructions, commands, examples, and output references.

Possibly related PRs

• docs: updates suga.yaml example in quickstart #104: Updates docs/quickstart.mdx example content and suga.yaml examples—overlaps with quickstart example changes.
• docs: fix page ToCs, using headings instead of steps #117: Modifies the Suga Vale vocabulary accept list—overlaps with the uv vocabulary addition.
• docs: adding generate command to quickstart docs #71: Adds language-specific local development and client-generation steps in docs/quickstart.mdx—overlaps with the new language tabs and local dev guidance.

Suggested labels

documentation

Suggested reviewers

• davemooreuws
• tjholm
• HomelessDinosaur
• sean-nitric

Pre-merge checks

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The PR title "docs: update the quickstart guide with additional steps and ToC" directly corresponds to the primary changes in the changeset. The raw summary shows that docs/quickstart.mdx underwent a significant rework with reorganized markdown sections, added informational blocks, and tabbed language sections—all of which align with the title's mention of "additional steps and ToC." The title is concise, specific, and clearly communicates the main change without unnecessary noise.
Description Check	✅ Passed	The PR description is related to the changeset, referencing the issue being fixed (NIT-355) and explaining the draft status pending GCP Platform design finalization. While the description lacks detailed specifics about the quickstart content changes, it does provide meaningful context about the work's purpose and status. Since the check is lenient and only requires the description to be related in some way without requiring extensive detail, this meets the passing criteria.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 388b2c2 and dfd4493.

📒 Files selected for processing (1)

• docs/quickstart.mdx (3 hunks)

🧰 Additional context used

🪛 LanguageTool

docs/quickstart.mdx

[grammar] ~128-~128: There might be a mistake here.
Context: ... name: app ``` The template includes: - target: AWS deployment configuration -...

(QB_NEW_EN)

---

[grammar] ~129-~129: There might be a mistake here.
Context: ...target: AWS deployment configuration - services: Your app service with loca...

(QB_NEW_EN)

---

[grammar] ~130-~130: There might be a mistake here.
Context: ...al dev script and Docker container setup - buckets: A files bucket that your ap...

(QB_NEW_EN)

---

[grammar] ~131-~131: There might be a mistake here.
Context: ...that your app can read from and write to - entrypoints: An HTTP endpoint that rou...

(QB_NEW_EN)

---

[style] ~274-~274: Consider using a less common alternative to make your writing sound more unique and professional.
Context: ...'ll start with a basic option here, but feel free to use your preferred method. <T...

(FEEL_FREE_TO_STYLE_ME)

---

[style] ~368-~368: Consider shortening or rephrasing this to strengthen your wording.
Context: ...i.my-first-app.example.com" ``` If you make changes to your application in the future, you can...

(MAKE_CHANGES)

---

[grammar] ~378-~378: There might be a mistake here.
Context: ...arning about Suga: - Projects overview - Platforms overview - [Add S...

(QB_NEW_EN)

---

[grammar] ~379-~379: There might be a mistake here.
Context: ...erview](/projects) - Platforms overview - [Add Suga to an existing application](/gu...

(QB_NEW_EN)

🔇 Additional comments (4)

docs/quickstart.mdx (4)

33-35: Verify the authentication statement aligns with product design.

Line 34's statement "In the future, certain features may be made available without signing in" — while clearer than previous wording — still merits verification. Please confirm with product that this accurately reflects the planned early-access authentication model.

---

142-177: Multi-language development section is well-structured.

The tabbed examples for Node.js, Python, and Go provide clear, language-specific guidance for dependency installation and client generation. The Python tab's dual-option (uv sync vs pip) is especially helpful.

---

272-336: Provider configuration sections are clear and complete.

The AWS/GCP tabs provide appropriate setup guidance, including minimal-steps philosophy for AWS (provider.tf region config) and variable-based setup for GCP (terraform.tfvars with DNS/project config). The note at lines 334–336 that these files persist across rebuilds is valuable.

---

368-372: Confirmed: past review comments addressed.

Lines 368 and 370–372 correctly incorporate prior feedback: "in the future" (US English) and the terraform destroy warning are both properly placed.

Confirm that no explicit Table of Contents (e.g., a markdown-generated TOC) is required per the PR objective. The well-organized section headings serve as an effective implicit TOC, but verify with the author if a formal TOC block was intended.

---

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.}

[raksiv]

Nice and clear updates so far!

[coderabbitai]

Actionable comments posted: 2

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 94c5aed and 2ff929f.

📒 Files selected for processing (2)

• docs/.vale/styles/config/vocabularies/Suga/accept.txt (1 hunks)
• docs/quickstart.mdx (3 hunks)

🧰 Additional context used

🪛 LanguageTool

docs/quickstart.mdx

[grammar] ~128-~128: There might be a mistake here.
Context: ... name: app ``` The template includes: - target: AWS deployment configuration -...

(QB_NEW_EN)

---

[grammar] ~129-~129: There might be a mistake here.
Context: ...target: AWS deployment configuration - services: Your app service with loca...

(QB_NEW_EN)

---

[grammar] ~130-~130: There might be a mistake here.
Context: ...al dev script and Docker container setup - buckets: A files bucket that your ap...

(QB_NEW_EN)

---

[grammar] ~131-~131: There might be a mistake here.
Context: ...that your app can read from and write to - entrypoints: An HTTP endpoint that rou...

(QB_NEW_EN)

---

[style] ~274-~274: Consider using a less common alternative to make your writing sound more unique and professional.
Context: ...'ll start with a basic option here, but feel free to use your preferred method. <T...

(FEEL_FREE_TO_STYLE_ME)

---

[style] ~368-~368: Consider shortening or rephrasing this to strengthen your wording.
Context: ...i.my-first-app.example.com" ``` If you make changes to your application in future, you can re-...

(MAKE_CHANGES)

---

[locale-violation] ~368-~368: The phrase ‘in future’ is British English. Did you mean: “in the future”?
Context: ...If you make changes to your application in future, you can re-run suga build to update ...

(IN_FUTURE)

---

[grammar] ~378-~378: There might be a mistake here.
Context: ...arning about Suga: - Projects overview - Platforms overview - [Add S...

(QB_NEW_EN)

---

[grammar] ~379-~379: There might be a mistake here.
Context: ...erview](/projects) - Platforms overview - [Add Suga to an existing application](/gu...

(QB_NEW_EN)

🔇 Additional comments (5)

docs/.vale/styles/config/vocabularies/Suga/accept.txt (1)

282-282: Vocabulary term added for CLI tool.

Adding "uv" aligns with the Python template references in the updated quickstart guide.

docs/quickstart.mdx (4)

128-133: List formatting is clear, grammar warnings are likely false positives.

The bullet-point list describing the template components reads well and is properly formatted for Markdown. The static analysis warnings appear to be false positives and can be safely ignored.

---

142-177: Excellent tabbed structure for multi-language guidance.

The addition of language-specific tabs (Node.js, Python, Go) with appropriate dependency and code generation commands makes the local development setup much clearer and more inclusive for different development environments.

---

272-287: Cloud provider credentials section well-organized.

The tabbed AWS/GCP configuration is a solid improvement. Grouping provider setup instructions separately makes the guide more maintainable and easier to extend if new providers are added.

---

305-332: Provider-specific configuration guidance is well-structured.

The separate AWS and GCP subsections with tabbed provider.tf and terraform.tfvars examples provide clear, actionable setup instructions. The note at line 335 about file persistence is helpful.