Skip to content

refactor: Improve AWS docs#475

Open
Mustafa-Esoofally wants to merge 16 commits intomainfrom
update/aws-docs
Open

refactor: Improve AWS docs#475
Mustafa-Esoofally wants to merge 16 commits intomainfrom
update/aws-docs

Conversation

@Mustafa-Esoofally
Copy link
Contributor

Summary

Comprehensive improvements to the AWS production documentation:

  • Restructured Getting Started with Tabs component (AWS Console as default, CLI as alternative)
  • Added Mintlify components: Frame for architecture diagram, CardGroup for Next Steps, AccordionGroup for troubleshooting
  • Updated architecture SVGs: HTTPS now required (not optional), removed /health endpoint display
  • Cleaned up navigation: Removed redundant "Next Step" sections (Mintlify auto-generates prev/next)
  • Renamed sidebar: "Connect" → "Connect to AgentOS" for clarity
  • Added SEO keywords to all 17 AWS pages for improved search

Pages Updated

Category Pages
Entry getting-started
Go Live verify, https, connect
Configure secrets, settings, database, efs, local, packages
Operate updates, ci-cd, monitoring, troubleshooting
Reference code-quality, database-tables, env-vars

Test plan

  • Verify mintlify dev renders all pages correctly
  • Check Tabs default to AWS Console
  • Verify CardGroup displays 3 columns
  • Confirm AccordionGroups expand/collapse
  • Test search finds pages by new keywords

🤖 Generated with Claude Code

Mustafa-Esoofally and others added 4 commits February 2, 2026 14:42
- Reorganize into logical sections: After Deploy, Configure, Operate, Reference
- Add "What You'll Deploy" table combining resources and costs upfront
- Group deployment steps with section headers (Prerequisites, Setup, Configure, Deploy)
- Use stepNumber prop for continuous 1-12 numbering across sections
- Fix broken os.agno.com flow (requires HTTPS first)
- Add missing ECR setup steps
- Fix project structure to match actual template
- Create new pages: verify.mdx, https.mdx, connect.mdx
- Move reference content: env-vars, database-tables, troubleshooting

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Rename "After Deploy" section to "Go Live" in navigation
- Restore 10 dashboard images to CI/CD page:
  - GitHub Actions secrets, Docker build workflow
  - OIDC provider setup (4 screenshots)
  - IAM role creation steps
  - ECR build workflow
- Restore 3 AWS Console images to HTTPS page:
  - Route 53 A record configuration
  - ACM certificate request
  - Certificate validation with CNAME

Images existed in /images/ but references were lost during restructure.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Restores format and validate documentation that was lost during restructure:
- ./scripts/format.sh and ./scripts/validate.sh usage
- Direct ruff and mypy commands
- Pre-commit workflow
- Common issues troubleshooting

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@Mustafa-Esoofally Mustafa-Esoofally changed the title refactor: Improve AWS docs with Mintlify components and SEO refactor: Improve AWS docs Feb 3, 2026
- Replace SVG with 2x PNG for better text readability
- Add w-full class for full-width display
- Uses Mintlify's built-in click-to-zoom lightbox
- Reorder sidebar: Configure → Go Live → Manage → More
- Rename folders: operate → manage, reference → more
- Create deploy/ folder, move updates.mdx there
- Merge Deploy into Go Live section
- Rename top-level tab: Production → Deploy
- Convert Next Steps to CardGroup components
- Remove database-tables.mdx (intentional)
- Update all internal links
- Replace hardcoded agentos-aws-template-prd with {infra_name} in efs.mdx
- Add Next Steps sections to troubleshooting.mdx, code-quality.mdx, env-vars.mdx
- troubleshooting: link to Code Quality and Env Vars (next in flow)
- code-quality: link to Env Vars and Getting Started
- env-vars: link to Getting Started and Deploy Updates
- deploy/updates: Replace CI/CD, Monitoring, Troubleshooting with
  Verify, HTTPS, Connect, CI/CD (matches Go Live flow)
- settings: Replace Deploy with EFS (stays in Configure section)
- local: Replace CI/CD with Packages (next in Configure)
- packages: Remove backwards Local link, keep only Deploy
Remove internal-linking Next Steps from AWS docs pages. These were
redundant with Mintlify's built-in < prev | next > navigation and
causing confusion.

Keep Next Steps only on:
- getting-started.mdx (hub page with section entry points)
- connect.mdx (end of flow, now points outside AWS to Agents/Tools/Knowledge)

This follows the Railway template pattern where Next Steps only appear
at the end of a flow to guide users to their next task.
- secrets.mdx: Show default agentos-aws-template-prd values that work
  out-of-the-box, with note for users who changed infra_name
- ci-cd.mdx: Fix broken anchor link to point to getting-started#step-1-aws-setup
Rename folders to match sidebar group names:
- deploy/ + after-deploy/ → go-live/

This improves codebase navigation by aligning file paths with
user-facing sidebar labels.

Updated all internal links to use new paths.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant