Merge pull request #264 from deploystackio/feat/mintlify

Feat/mintlify

Author: Lasim

.github/workflows/deploy_preview.yml .github/workflows/__deploy_preview.yml__.github/workflows/deploy_preview.yml renamed to .github/workflows/__deploy_preview.yml__

@@ -34,10 +34,7 @@ jobs:
         run: npm run lint:md
 
       - name: Run Lint Links
-        run: npm run lint:links
-
-      - name: Run Lint Links
-        run: npm run build        
+        run: npm run lint:links     
 
   release:
     name: Run Release

.github/workflows/deploy_prod.yml .github/workflows/__deploy_prod.yml__.github/workflows/deploy_prod.yml renamed to .github/workflows/__deploy_prod.yml__

@@ -1,128 +1,264 @@
 # DeployStack Documentation
 
-This repository contains the official documentation site for [DeployStack](https://deploystack.io/docs/), The Complete MCP Management Platform, built with [fumadocs](https://fumadocs.vercel.app/). Visit [deploystack.io](https://deploystack.io) to learn more about our platform.
+This repository contains the official documentation for [DeployStack](https://docs.deploystack.io/) - The First MCP-as-a-Service Platform. Built with [Mintlify](https://mintlify.com), our documentation provides a modern, searchable experience for developers building with DeployStack's satellite infrastructure.
+
+Visit [docs.deploystack.io](https://docs.deploystack.io) to explore the live documentation.
 
 ## Technology Stack
 
-- **Framework**: Next.js 15 with App Router
-- **Documentation**: Fumadocs for modern docs experience
+- **Documentation Platform**: Mintlify
 - **Content**: MDX (Markdown + React components)
-- **Styling**: Tailwind CSS
-- **Language**: TypeScript
+- **Deployment**: Automatic deployment via Mintlify platform
 
 ## Project Structure
 
 ```text
 .
-├── docs/                  # Documentation content (MDX files)
-│   ├── development/       # Development documentation
-│   │   ├── backend/       # Backend development guides
-│   │   ├── frontend/      # Frontend development guides
-│   │   └── gateway/       # Gateway architecture & implementation
-│   ├── self-hosted/       # Self-hosting guides
-│   ├── deploystack/       # Core DeployStack documentation
-│   ├── assets/            # Images and static assets
-│   └── ...                # MCP guides and configuration docs
-├── app/                   # Next.js app directory (fumadocs framework)
-├── lib/                   # Documentation utilities & components
-└── source.config.ts       # Fumadocs configuration
+├── general/               # Getting started and core concepts
+│   ├── architecture.mdx   # System architecture overview
+│   ├── teams.mdx          # Team management
+│   ├── roles.mdx          # Role-based access control
+│   └── mcp-*.mdx          # MCP server guides
+├── self-hosted/           # Self-hosting guides
+│   ├── quick-start.mdx    # Quick start guide
+│   ├── setup.mdx          # Installation instructions
+│   └── docker-compose.mdx # Docker deployment
+├── development/           # Development documentation
+│   ├── frontend/          # Frontend development guides
+│   │   ├── index.mdx      # Frontend overview
+│   │   ├── ui/            # UI system documentation
+│   │   └── ...
+│   ├── backend/           # Backend development guides
+│   │   ├── index.mdx      # Backend overview
+│   │   ├── api/           # API documentation
+│   │   ├── database/      # Database guides
+│   │   └── ...
+│   └── satellite/         # Satellite development guides
+│       ├── index.mdx      # Satellite overview
+│       ├── architecture.mdx
+│       └── ...
+├── assets/                # Images and static assets
+│   └── images/
+│       ├── logo/          # Logo files
+│       └── ...
+├── docs.json              # Mintlify configuration
+├── index.mdx              # Documentation home page
+└── README.md              # This file
 ```
 
-**Note**: The `app/` directory contains the fumadocs framework setup and should not be modified for content changes. All documentation content goes in the `docs/` directory.
+## Local Development
 
-## Development Setup
+Mintlify provides a local development CLI for previewing documentation changes:
 
 ```bash
-# Install dependencies
-npm ci
+# Install Mintlify CLI globally (one-time setup)
+npm install -g mintlify
+
+# Start local development server
+mintlify dev
+
+# The documentation will be available at http://localhost:3000
+```
+
+The local server provides:
+- Hot reloading for instant content updates
+- Navigation preview
+- Component rendering
+- Dark/light mode testing
+
+## Writing Documentation
+
+### Content Format
+
+All documentation is written in **MDX** (Markdown with JSX components):
 
-# Start documentation development server (http://localhost:3000)
-npm run dev
+```mdx
+---
+title: Your Page Title
+description: A brief description of the page content
+---
 
-# Build documentation site for production
-npm run build
+# Your Page Title
 
-# Start production server
-npm run start
+Write your content here using standard Markdown syntax.
 
-# Validate documentation quality
-npm run lint:md      # Markdown linting
-npm run lint:links   # Link validation
+<Info>
+Use Mintlify components for callouts and special content blocks.
+</Info>
+
+## Section Header
+
+More content here...
 ```
 
-## Contributing Guidelines
+### Mintlify Components
 
-### Writing Documentation
+Mintlify provides built-in components for enhanced documentation:
 
-1. **Content Format**: Write all documentation in MDX format (`.mdx` files)
-2. **Location**: Store all content in the `docs/` directory
-3. **Navigation**: Use `meta.json` files in each directory to control navigation structure
-4. **Assets**: Place images in `docs/assets/images/` with appropriate subdirectories
-5. **Links**: Use absolute paths for all references:
-   - Documentation: `/docs/development/gateway/`
-   - Images: `/docs/assets/images/example.png`
-6. **Brand Colors**: Use the primary color (`text-primary`, `bg-primary`) for consistency - avoid introducing other accent colors
+**Callouts:**
+```mdx
+<Note>General information</Note>
+<Info>Important information</Info>
+<Tip>Helpful tips</Tip>
+<Warning>Important warnings</Warning>
+<Check>Success status</Check>
+<Danger>Critical warnings</Danger>
+```
 
-### Navigation Structure
+**Code Groups:**
+```mdx
+<CodeGroup>
+```bash macOS/Linux
+npm install
+```
 
-Fumadocs automatically generates navigation from your file structure and `meta.json` files:
+```powershell Windows
+npm install
+```
+</CodeGroup>
+```
 
-- Each directory can have a `meta.json` file to configure its appearance in navigation
-- File-based routing: `docs/deploystack/index.mdx` becomes `/docs/deploystack`
-- Nested directories create hierarchical navigation
+**Cards:**
+```mdx
+<CardGroup cols={2}>
+  <Card title="Getting Started" icon="rocket" href="/general/quick-start">
+    Begin your DeployStack journey
+  </Card>
+  <Card title="API Reference" icon="code" href="/development/backend/api">
+    Explore the API documentation
+  </Card>
+</CardGroup>
+```
 
-### Adding New Content
+**Steps:**
+```mdx
+<Steps>
+  <Step title="Install Dependencies">
+    Run `npm install` to install required packages
+  </Step>
+  <Step title="Configure Environment">
+    Set up your environment variables
+  </Step>
+  <Step title="Start Development">
+    Run `npm run dev` to start the development server
+  </Step>
+</Steps>
+```
 
-1. Create new `.mdx` files in the appropriate `docs/` subdirectory
-2. Add or update `meta.json` files to control navigation
-3. Follow established naming conventions
-4. Ensure all links use absolute paths
-5. Test locally with `npm run dev`
+### Navigation Configuration
 
-### Asset Management
+Navigation is controlled via `docs.json`:
 
-For diagrams and images:
+- **Tabs**: Top-level navigation sections (General, Self Hosted, Frontend Development, etc.)
+- **Groups**: Subsections within each tab
+- **Pages**: Individual documentation pages
 
-1. Use [drow.io](https://app.diagrams.net/) for creating diagrams
-2. Export as PNG or WebP format
-3. Optimize images for web (compress file sizes)
-4. Place files in appropriate subdirectories under `docs/assets/images/`
+To add a new page:
+1. Create the `.mdx` file in the appropriate directory
+2. Add the page path to `docs.json` under the relevant group
+3. Test locally with `mintlify dev`
 
-## Deployment Process
+### Content Guidelines
 
-Our deployment uses a two-branch workflow:
+**File Naming:**
+- Use kebab-case: `my-new-page.mdx`
+- Index files represent the directory: `index.mdx`
 
-- **`main`**: Development branch for content updates and testing
-- **`prod`**: Production branch that deploys to [deploystack.io/docs](https://deploystack.io/docs)
+**Links:**
+- Use absolute paths from documentation root: `/development/backend/api/index`
+- Mintlify automatically handles `.mdx` extensions
+
+**Images:**
+- Store in `assets/images/` with logical subdirectories
+- Reference with absolute paths: `/assets/images/logo/dark.webp`
+- Optimize images before committing (compress file sizes)
+
+**Frontmatter:**
+```yaml
+---
+title: Page Title (required)
+description: Page description for SEO (required)
+---
+```
+
+## Asset Management
+
+### Images and Diagrams
+
+1. **Diagrams**: Create with [draw.io](https://app.diagrams.net/)
+2. **Export Format**: PNG or WebP
+3. **Optimization**: Compress images before committing
+4. **Location**: Store in `assets/images/` with appropriate subdirectories
+
+## Contributing Guidelines
 
 ### Workflow
 
-1. Create feature branches from `main`
-2. Submit pull requests to `main`
-3. After approval and merge to `main`, changes are automatically validated
-4. Merge to `prod` to deploy to production
+1. **Fork or Branch**: Create a feature branch from `main`
+2. **Write Content**: Add or update documentation in MDX format
+3. **Test Locally**: Run `mintlify dev` to preview changes
+4. **Submit PR**: Create a pull request to `main` branch
+5. **Review**: Wait for review and address feedback
+6. **Merge**: Changes are automatically deployed after merge
 
-### Continuous Integration
+### Pull Request Guidelines
 
-The CI pipeline includes:
+- Write clear commit messages
+- Test all links and navigation
+- Verify code examples are correct
+- Check for spelling and grammar
+- Ensure images load correctly
+- Preview on mobile and desktop layouts
 
-- Markdown linting and validation
-- Link checking to prevent broken links
-- Automatic fumadocs build verification
-- Production deployment triggers
+### Documentation Standards
 
-## Local Development
+**Writing Style:**
+- Write in clear, concise language
+- Use active voice
+- Address the reader directly ("you")
+- Avoid jargon without explanation
+- Include code examples where helpful
+
+**Code Examples:**
+- Include complete, working examples
+- Add comments for clarity
+- Show expected output when relevant
+- Test all code before committing
+
+**Structure:**
+- Start with overview/introduction
+- Progress from basic to advanced
+- Use descriptive section headers
+- Include related documentation links at the end
+
+## Deployment
+
+### Automatic Deployment
+
+Mintlify automatically deploys documentation when changes are merged to `main`:
+
+- **Trigger**: Push or merge to `main` branch
+- **Build**: Mintlify builds the documentation
+- **Deploy**: Changes go live at docs.deploystack.io
+- **CDN**: Content served via Mintlify's global CDN
+
+### Branch Strategy
+
+- **`main`**: Production branch that deploys to docs.deploystack.io
+- **Feature Branches**: Create from `main` for new content or updates
+- **Pull Requests**: All changes must go through PR review
 
-When running `npm run dev`, the documentation site will be available at `http://localhost:3000`. The fumadocs framework provides:
+## Need Help?
 
-- Hot reloading for content changes
-- Automatic navigation generation
-- Built-in search functionality
-- Responsive design
-- Dark/light mode support
+- 📚 **Documentation**: [docs.deploystack.io](https://docs.deploystack.io)
+- 💬 **Discord**: [Join our community](https://discord.gg/42Ce3S7b3b)
+- 🐛 **Issues**: [GitHub Issues](https://github.com/deploystackio/documentation/issues)
+- 🌐 **Website**: [deploystack.io](https://deploystack.io)
+- 🚀 **Dashboard**: [cloud.deploystack.io](https://cloud.deploystack.io)
 
-## 💬 Need Help?
+## Links
 
-- 📚 Check our [Documentation](https://deploystack.io/docs)
-- 🎯 Report issues on [GitHub](https://github.com/deploystackio/documentation/issues)
-- 📧 Join our Discord at [https://discord.gg/UjFWwByB](https://discord.gg/UjFWwByB)
+- [Mintlify Documentation](https://mintlify.com/docs)
+- [MDX Documentation](https://mdxjs.com/)
+- [DeployStack Main Repository](https://github.com/deploystackio/deploystack)
+- [DeployStack Changelog](https://deploystack.io/changelog)