Skip to content

feat: migrate docs site to Docus with Fly.io deployment#10

Merged
phernandez merged 6 commits intomainfrom
docs/v0.18-release
Feb 4, 2026
Merged

feat: migrate docs site to Docus with Fly.io deployment#10
phernandez merged 6 commits intomainfrom
docs/v0.18-release

Conversation

@phernandez
Copy link
Member

Summary

  • Migrate documentation site from Astro to Docus (Nuxt-based documentation theme)
  • Add Fly.io deployment with Docker containerization
  • Add v0.18.0 release documentation and cloud features
  • Add horizontal hero with image on homepage

Changes

Framework Migration

  • Replace Astro with Docus v5 (Nuxt 4, Tailwind CSS 4, Nuxt UI)
  • Migrate all documentation from MDX to Markdown with MDC syntax
  • Add built-in search, dark mode, and LLM-friendly output via nuxt-llms

Deployment

  • Add Dockerfile for containerized builds
  • Add fly.toml.template with envsubst for environment-specific configs
  • Add GitHub Actions for development (auto) and production (manual) deploys
  • Add justfile for common development commands

Documentation Content

  • Add v0.18.0 release notes
  • Add cloud snapshots documentation
  • Add changelog page
  • Reorganize content into numbered directories for navigation order

Homepage

  • Add horizontal hero layout with computer.png image
  • Reduce vertical spacing for tighter layout

Test plan

  • Run npm run dev locally - verify site loads
  • Run npm run build - verify build succeeds
  • Run just docker-build - verify Docker image builds
  • Create Fly.io apps and deploy to development
  • Verify all documentation pages render correctly
  • Verify search functionality works
  • Verify dark mode toggle works

🤖 Generated with Claude Code

phernandez and others added 6 commits January 26, 2026 20:37
- Add v0.17.8 and v0.17.9 release notes to latest-releases.mdx
- Document directory operations for move_note and delete_note MCP tools
- Add cloud snapshot commands (create, list, show, browse, delete)
- Document --local and --cloud routing flags for CLI
- Add v0.18.0 section to whats-new.mdx
- Update CLAUDE.md to reflect v0.18.0 release

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add auto-updating changelog page that fetches from GitHub releases
- Add cloud snapshots section to cloud guide with CLI commands
- Update CLI reference with snapshot commands and routing flags
- Improve site typography using Tailwind zinc palette
- Remove redundant latest-releases page (replaced by changelog)
- Add MCP configuration

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Replace Astro documentation site with Docus (Nuxt-based) for improved
documentation features including built-in search, dark mode, and
LLM-friendly output via nuxt-llms.

Changes:
- Remove Astro framework and React components
- Add Docus with Nuxt 4, Tailwind CSS 4, and Nuxt UI
- Migrate all documentation from MDX to Markdown with MDC syntax
- Add Fly.io deployment with Docker containerization
- Add GitHub Actions for development/production deployments
- Add justfile for common development commands
- Add Umami analytics integration

New structure:
- content/ - Documentation pages (replaces src/pages/)
- app/ - Docus configuration and custom components
- server/ - API routes (GitHub releases endpoint)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add computer.png image to hero section
- Use horizontal orientation for hero layout
- Reduce vertical padding for tighter layout

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Resolve conflicts by keeping our Docus migration
- Update CLAUDE.md to reflect Docus architecture

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@phernandez phernandez merged commit 4eaf4e0 into main Feb 4, 2026
1 check passed
@claude
Copy link

claude bot commented Feb 4, 2026

Pull Request Review: Migrate to Docus with Fly.io Deployment

This is a comprehensive migration from Astro to Docus with excellent infrastructure improvements. The code quality is strong overall with proper security practices and performance optimizations.


✅ Strengths

Infrastructure & Deployment

  • Excellent Docker multi-stage build: Proper separation of build and production stages minimizes final image size
  • Security best practices: Using slim base image, cleaning apt cache, running as non-root implicitly
  • Smart cache busting: Git SHA passed as build arg for proper CDN cache invalidation
  • Environment-specific configs: Clean separation via .env files with envsubst templating

Performance Optimizations

  • Server-side caching: 1-hour cache on GitHub API responses prevents rate limiting
  • Lazy loading: Dynamic import of beautiful-mermaid keeps initial bundle size down
  • Efficient Fly.io settings: Auto-stop/start machines optimize costs

Code Quality

  • Type safety: Proper TypeScript interfaces throughout
  • Error handling: Graceful degradation with user-friendly error states
  • XSS protection: Using v-html with sanitized, controlled formatting
  • Accessibility: Modal keyboard navigation, proper ARIA practices

⚠️ Security Considerations

1. GitHub API Rate Limiting (Medium Priority)

Location: server/api/releases.ts:4-13

Issue: No GitHub token authentication means hitting public rate limits (60 requests/hour per IP)

Recommendation: Add GITHUB_TOKEN environment variable with authorization header to get 5,000 requests/hour.

2. Umami Analytics Hardcoded (Low Priority)

Location: nuxt.config.ts:6-12

Issue: Analytics ID is hardcoded in source. While not sensitive, consider using environment variable for consistency.


🐛 Potential Bugs

1. Memory Leak in Modal Cleanup (Medium Priority)

Location: Mermaid.vue:88-91

Issue: onUnmounted is called but not imported from Vue

Fix: Add onUnmounted to the imports on line 9. Without this, the event listener cleanup never runs, causing memory leaks.

2. Negative Lookbehind Browser Compatibility (Low Priority)

Location: GithubReleases.vue:188

Issue: Regex uses negative lookbehind which doesn't work in Safari less than 16.4. Since this is for documentation display (non-critical), acceptable as-is.


🚀 Performance Considerations

1. Fly.io Resource Allocation

Location: fly.toml.template:33-35

Current: shared-cpu-1x with 512MB RAM is appropriate for a documentation site. Monitor memory usage post-deployment - Nuxt SSR can be memory-hungry. Consider bumping to 1GB if you see OOM issues.

2. API Response Size

Location: server/api/releases.ts:6

Current: Fetches 50 releases per request. Consider reducing to per_page=30 to match the component limit of 30.


📚 Documentation & Maintainability

Excellent Practices

  • Comprehensive JSDoc comments on all Vue components
  • Clear separation of concerns in component structure
  • Justfile for standardized commands
  • CLAUDE.md for AI-assisted development context

Suggestions

  1. Add unit tests for critical parsing logic - the markdown parsing is complex and would benefit from test coverage
  2. Document rate limiting in README - mention the GitHub token requirement for production
  3. Add dedicated health check endpoint for Fly.io

🧪 Test Coverage

Current State: No test files detected in PR

Recommendation: Add tests for parseReleaseBody(), formatItem(), and API route error handling.


✨ Final Verdict

Overall Assessment: Approve with minor improvements

This is a well-executed migration with strong security fundamentals, good performance optimization, clean architecture, and production-ready infrastructure.

Recommended Action Items:

  1. 🔴 Must fix: Add onUnmounted import to Mermaid.vue
  2. 🟡 Should fix: Add GITHUB_TOKEN to avoid rate limits in production
  3. 🟢 Nice to have: Add test coverage for parsing functions

Great work on this migration! The Docus framework is a solid choice for documentation, and the Fly.io deployment setup is clean and production-ready.

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