docs: add projects and platforms documentation#78
Conversation
jyecusch
requested review from
HomelessDinosaur,
davemooreuws,
sean-nitric and
tjholm
WalkthroughAdded new vocabulary accept terms (Fargate, Linode, Vultr, booleans, CDNs); updated docs navigation by adding "Core Concepts" with pages ["projects","platforms"] and "Resources" with ["registry"]; replaced and expanded introduction text and swapped poster image to PNG; added three new docs pages: docs/registry.mdx, docs/platforms.mdx, and docs/projects.mdx. Possibly related PRs
Suggested labels
Suggested reviewers
Pre-merge checks✅ Passed checks (3 passed)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
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. Comment |
jyecusch
force-pushed
the
platform-docs
branch
from
2d9f8a8 to
250eb52
Compare
jyecusch
force-pushed
the
platform-docs
branch
from
250eb52 to
2c686de
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (5)
docs/.vale/styles/config/vocabularies/Suga/accept.txt (1)
15-19: Preempt Vale noise: add missing platform/service terms.Docs mention CloudFront, Cloud Run, Cloud CDN, HCL, tfvars, and Workspaces. Add them to avoid false positives.
Fargate Linode Vultr booleans CDNs +CloudFront +Cloud Run +Cloud CDN +HCL +tfvars +Workspacesdocs/introduction.mdx (1)
53-59: Fix Azure support phrasing (conflicts with “coming soon” below).Azure is “coming soon” later (Lines 157–162), but this bullet implies parity today. Reword:
-- **Multi-cloud deployment** - Generate Terraform for AWS, GCP, or Azure from the same design while maintaining governance +- **Multi-cloud deployment** - Generate Terraform for AWS and GCP today; Azure coming soondocs/platforms/index.mdx (2)
32-39: Clarify current official support.Add a brief note under Official Platforms that, as of now, only AWS and GCP are officially supported; Azure is coming soon. Keeps expectations clear.
### Official Platforms @@ The Suga team maintains official platforms for major cloud providers. These are general purpose, production-ready implementations: - **[AWS Platform](https://app.addsuga.com/platforms/suga/aws)** - Lambda/Fargate services, S3 storage, CloudFront CDN, IAM security - **[GCP Platform](https://app.addsuga.com/platforms/suga/gcp)** - Cloud Run services, Cloud Storage, Cloud CDN, Service Account security - **Azure Platform** _(coming soon)_ - Container Apps services, Blob Storage, etc. + +<Info> +Today, Suga officially supports AWS and GCP. Azure support is in progress. +</Info>
20-25: Minor wording tweak for clarity.“Establishing routes between CloudFront and AWS Lambda/Fargate” → “Configuring routing and IAM between CloudFront and Lambda/Fargate” reads cleaner.
docs/projects/index.mdx (1)
171-177: Align service name in database example.Earlier examples define service “app,” but DB access uses “api.” Use “app” for consistency.
databases: main: access: - api: + app: - query
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (3)
docs/images/blueprint-property-editor.pngis excluded by!**/*.pngdocs/images/blueprint-vars-as-properties.pngis excluded by!**/*.pngdocs/images/platform-vars.pngis excluded by!**/*.png
📒 Files selected for processing (6)
docs/.vale/styles/config/vocabularies/Suga/accept.txt(1 hunks)docs/docs.json(2 hunks)docs/introduction.mdx(3 hunks)docs/platforms/index.mdx(1 hunks)docs/projects/index.mdx(1 hunks)docs/registry.mdx(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-09-08T23:49:28.580Z
Learnt from: jyecusch
PR: nitrictech/suga#49
File: docs/quickstart.mdx:0-0
Timestamp: 2025-09-08T23:49:28.580Z
Learning: Suga currently only officially supports AWS (`suga/aws1`) and GCP (`suga/gcp1`) as deployment targets. Azure is not yet supported as a deployment target, despite `az login` being a valid Azure CLI authentication command.
Applied to files:
docs/introduction.mdx
🔇 Additional comments (2)
docs/registry.mdx (1)
1-4: Confirm Mintlify behavior for front‑matterurl.If Mintlify doesn’t auto‑redirect when
urlis set, this page will render blank. Consider adding a one‑liner with an external link Card, or move the external href into docs.json.docs/introduction.mdx (1)
144-155: Unify stack output path across docs — pick one canonical path (recommend terraform/stacks).Docs currently use both terraform/stacks/... and .suga/stacks/...; choose one and update all occurrences. Recommend terraform/stacks (CDKTF synth default); confirm the CLI actually writes that directory and update CLI docs if needed.
terraform/stacks references: docs/introduction.mdx, docs/guides/terraform-backend-config.mdx, docs/guides/database-migration.mdx, docs/guides/aws/environment-management.mdx
.suga/stacks references: docs/projects/index.mdx, docs/quickstart.mdx, docs/cli/build.mdx, docs/guides/add-suga.mdx
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
docs/projects/index.mdx (3)
15-30: Non-standard Tailwind class h-15.Unless you’ve extended the spacing scale, h-15 won’t render. Prefer a standard token.
- <div className="absolute bottom-0 left-0 right-0 h-15 bg-gradient-to-t from-white to-transparent dark:from-gray-900 pointer-events-none"></div> + <div className="absolute bottom-0 left-0 right-0 h-16 bg-gradient-to-t from-white to-transparent dark:from-gray-900 pointer-events-none"></div>
245-251: Tighten deploy snippet.Suggest including terraform plan for safer workflows and clarify wildcard cd.
-cd .suga/stacks/my-app-aws-* -terraform init -terraform apply +cd .suga/stacks/my-app-aws-* # adjust to your generated stack dir +terraform init +terraform plan +terraform apply
16-28: Respect reduced motion.Autoplaying video can impact users with motion sensitivity. Consider skipping autoplay when prefers-reduced-motion is set.
- <video + <video className="w-full h-full object-cover object-top" - autoPlay + autoPlay loop muted playsInline preload="metadata" poster="/images/project-editor-poster.png" aria-label="Demo of the Suga visual project editor showing drag-and-drop infrastructure design" > + {/* Consider: disable autoplay if user prefers reduced motion */} + {/* CSS/JS gate: @media (prefers-reduced-motion: reduce) { video[autoplay] { animation: none; } } */}
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
docs/images/project-editor-poster.pngis excluded by!**/*.png
📒 Files selected for processing (2)
docs/introduction.mdx(4 hunks)docs/projects/index.mdx(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/introduction.mdx
🧰 Additional context used
🧠 Learnings (1)
📓 Common learnings
Learnt from: jyecusch
PR: nitrictech/suga#78
File: docs/docs.json:24-27
Timestamp: 2025-09-22T21:56:58.963Z
Learning: When analyzing docs.json navigation structures, ensure to carefully verify the actual JSON structure before flagging navigation mismatches. The "Core Concepts" and "Resources" groups in docs/docs.json are correctly configured with their corresponding MDX files.
🔇 Additional comments (4)
docs/projects/index.mdx (4)
23-27: Verify video assets exist and paths are correct.Poster was changed to .png, source is .webm. Ensure both files are committed at an appropriate static path used by the docs site (e.g., static/images or public/images) and that the leading slash resolves correctly in production.
Run to confirm presence:
#!/bin/bash # Find poster and video anywhere in repo (common static dirs included) fd -a -E node_modules -E dist -E build -E .suga -E .git \ -g 'project-editor-poster.{png,jpg}' -g 'project-editor.webm' || true
12-34: Confirm Tabs/Tab availability in MDX scope.If these aren’t globally registered, add imports or provider wiring; otherwise build will fail.
141-150: Confirm bucket seeding field and behavior.Verify the key is content_path (not contentPath or similar) and that seeding occurs at build/deploy as documented across all platforms.
36-38: Validate platform identifiers.
Found suga/aws@1 and suga/gcp@1 in docs: docs/projects/index.mdx (37, 82–83), docs/platforms/index.mdx (42–43), docs/quickstart.mdx (79, 199–200), docs/guides/add-suga.mdx (54). Confirm these are the canonical suga target IDs/versions for suga.yaml and update all occurrences if they’re placeholders or incorrect.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
docs/projects/index.mdx (2)
29-29: Tailwind class h-15 is non‑standard.h-15 isn’t a default size. Use a valid utility (e.g., h-16) or define a custom value.
- <div className="absolute bottom-0 left-0 right-0 h-15 bg-gradient-to-t from-white to-transparent dark:from-gray-900 pointer-events-none"></div> + <div className="absolute bottom-0 left-0 right-0 h-16 bg-gradient-to-t from-white to-transparent dark:from-gray-900 pointer-events-none"></div>
35-66: Tweak example ordering for readability.Minor doc polish: put name/description before targets to match typical project scaffolds.
-```yaml title="Example suga.yaml" -targets: - - suga/aws@1 - -name: my-app -description: An example web application with storage +```yaml title="Example suga.yaml" +name: my-app +description: An example web application with storage + +targets: + - suga/aws@1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/projects/index.mdx(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
📓 Common learnings
Learnt from: jyecusch
PR: nitrictech/suga#78
File: docs/docs.json:24-27
Timestamp: 2025-09-22T21:56:58.963Z
Learning: When analyzing docs.json navigation structures, ensure to carefully verify the actual JSON structure before flagging navigation mismatches. The "Core Concepts" and "Resources" groups in docs/docs.json are correctly configured with their corresponding MDX files.
🔇 Additional comments (4)
docs/projects/index.mdx (4)
15-30: Verify media assets exist (poster updated).Poster now points to .png; source is still .webm. Let’s confirm both files are committed to the repo and paths resolve in the site.
#!/bin/bash set -euo pipefail need=("project-editor.webm" "project-editor-poster.png") echo "Searching for media assets..." for n in "${need[@]}"; do hits=$(fd -a "$n" || true) if [[ -z "$hits" ]]; then echo "MISSING: $n" else echo "$n ->" echo "$hits" fi done # Optional: check for legacy .jpg poster that might still be referenced elsewhere fd -a "project-editor-poster.jpg" || true
155-163: Entrypoint routes and targets are consistent.“/” → public-assets and “/api/” → app aligns with the resource names above. Nice.
171-177: Database access service name fixed.Access now granted to app (not api). This resolves the earlier mismatch.
10-10: Confirm /platforms link resolvesCouldn't find docs/platforms/index.mdx though docs.json lists "platforms"; docs/projects/index.mdx (line 10) links to Platform. Verify the built site routes /platforms to the Platforms overview or add/update the page/link.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
docs/projects.mdx (2)
29-29: Tailwind class h-15 likely invalidUse a valid utility (e.g., h-16) or an arbitrary value.
- <div className="absolute bottom-0 left-0 right-0 h-15 bg-gradient-to-t from-white to-transparent dark:from-gray-900 pointer-events-none"></div> + <div className="absolute bottom-0 left-0 right-0 h-16 bg-gradient-to-t from-white to-transparent dark:from-gray-900 pointer-events-none"></div>
245-251: Glob in cd can be ambiguousIf multiple stacks exist, cd may fail. Suggest a first-match pattern or a placeholder.
-cd .suga/stacks/my-app-aws-* +cd "$(ls -d .suga/stacks/my-app-aws-* | head -n1)"
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/platforms.mdx(1 hunks)docs/projects.mdx(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- docs/platforms.mdx
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-08-28T06:12:17.266Z
Learnt from: davemooreuws
PR: nitrictech/suga#29
File: docs/guides/terraform-backend-config.mdx:0-0
Timestamp: 2025-08-28T06:12:17.266Z
Learning: The Suga project uses Mintlify for documentation. Mintlify provides built-in MDX components like <Steps> and <Step> that don't need to be defined or imported in the repository - they're available by default in Mintlify's documentation platform.
Applied to files:
docs/projects.mdx
🔇 Additional comments (6)
docs/projects.mdx (6)
15-30: Add MP4 fallback and verify media assets exist
- Some Safari/enterprise builds still lack WebM; include an MP4 source as fallback.
- Prior review flagged missing assets; new poster now .png. Re‑verify both files are committed.
Apply this diff to add the MP4 source:
<video className="w-full h-full object-cover object-top" autoPlay loop muted playsInline preload="metadata" poster="/images/project-editor-poster.png" aria-label="Demo of the Suga visual project editor showing drag-and-drop infrastructure design" > <source src="/images/project-editor.webm" type="video/webm" /> + <source src="/images/project-editor.mp4" type="video/mp4" /> Your browser does not support the video tag. </video>Run to verify assets:
#!/bin/bash for f in images/project-editor.webm images/project-editor-poster.png; do [[ -f "$f" ]] || echo "missing asset: $f" done
12-14: Confirm Tab icon compatibilityMintlify Tabs are fine, but icon="monitor-cog" and "file-code-2" depend on the icon set available in your theme. Verify they render; drop the icon prop if not.
35-66: YAML example reads clean and consistentServices, buckets, and routes align; good starter template.
81-84: Verify target slugs existConfirm suga/aws@1 and suga/gcp@1 are valid, published platform IDs in PR #77/registry. If GCP isn’t available yet, annotate as “coming soon” or omit.
169-177: Nice: service name consistency fixedDatabase access now references app (not api). Matches earlier examples.
209-217: Good addition: mention ofsuga editAddresses earlier feedback to surface the visual editor.
Co-authored-by: Ryan Cartwright <39504851+HomelessDinosaur@users.noreply.github.com>
Co-authored-by: Ryan Cartwright <39504851+HomelessDinosaur@users.noreply.github.com>
davemooreuws
left a comment
davemooreuws
left a comment
There was a problem hiding this comment.
Added a suggestion in the intro
Co-authored-by: David Moore <4121492+davemooreuws@users.noreply.github.com>
|
🎉 This PR is included in version 0.1.2 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
7 participants
Fixes: NIT-264
Adds documentation for the "Projects" and "Platforms" core concepts.
This includes: