​

FlowX.AI Documentation Development Rules

​

Development Environment Setup

​

Prerequisites

• Node.js: Version 18+ required for Mintlify CLI
• Docker: For containerized development (optional but recommended)
• Git: For version control and collaboration

​

Local Development Setup

​

Option 1: Native Development

# Install Mintlify CLI globally
npm i -g mintlify

# Navigate to project root (where docs.json is located)
cd /path/to/flowx-docs

# Start development server
mintlify dev

​

Option 2: Docker Development

# Build Docker image
source docker/run.sh --build

# Create and start container
source docker/run.sh --up

# Start container with Mintlify
source docker/run.sh --start --run-mintlify

​

Development Server Access

• Local URL: http://localhost:3000
• Docker URL: http://127.0.0.1:3000
• Hot reload enabled for content changes

​

File Structure and Organization

​

Repository Structure

flowx-docs/
├── .cursor/rules/           # Cursor AI rules and configurations
├── 5.0-tech-preview/        # Version 5.0 documentation
│   ├── docs/               # Main documentation content
│   ├── setup-guides/       # Installation and setup guides
│   ├── ai-platform/        # AI platform documentation
│   └── sdks/              # SDK documentation
├── 4.x/                    # Legacy version documentation
├── public/                 # Static assets (images, files)
├── docker/                 # Docker configuration
├── docs.json              # Mintlify configuration
├── custom.css             # Custom styling
└── README.md              # Project documentation

​

Version Management

• Current Development: 5.0-tech-preview/ directory
• Legacy Versions: 4.x/, 3.x/, etc.
• Version-Specific Content: Keep all content within version directories
• Shared Assets: Use public/ directory for cross-version assets

​

Content Development Workflow

​

Creating New Documentation

​

1. File Creation

# Create new MDX file with proper naming
touch 5.0-tech-preview/docs/category/new-feature.mdx

# Add required frontmatter
---
title: "New Feature Documentation"
description: "Comprehensive guide for the new feature"
---

​

2. Navigation Update

{
  "group": "Category Name",
  "pages": [
    "5.0-tech-preview/docs/category/existing-page",
    "5.0-tech-preview/docs/category/new-feature"
  ]
}

​

3. Content Development

• Follow FlowX terminology standards
• Use appropriate Mintlify components
• Include code examples and screenshots
• Add cross-references to related content

​

Content Review Process

​

Before Committing

• Test all code examples
• Verify all internal links work
• Check external links are accessible
• Validate Mintlify component syntax
• Ensure proper heading hierarchy
• Review for consistent terminology

​

Testing Commands

# Test local development server
mintlify dev

# Check for broken links (if link checker is available)
mintlify check-links

# Validate component syntax
mintlify validate

​

Docker Development Workflow

​

Docker Commands Reference

# Build image
source docker/run.sh --build

# Container management
source docker/run.sh --up          # Create and start
source docker/run.sh --down        # Stop and remove
source docker/run.sh --start       # Start existing
source docker/run.sh --stop        # Stop existing

# Development workflow
source docker/run.sh --start --run-mintlify  # Start with Mintlify

# Cleanup
source docker/run.sh --down
docker image rm docs-flowxai

​

Docker Development Benefits

• Consistent Environment: Same setup across all development machines
• Isolation: No conflicts with local Node.js installations
• Easy Cleanup: Remove containers and images when done
• macOS Optimized: Specifically configured for macOS development

​

Content Standards and Validation

​

File Naming Conventions

• Use kebab-case for all files and directories
• Make names descriptive and searchable
• Include version prefixes when necessary
• Avoid special characters and spaces

​

Content Validation Rules

• Frontmatter: Every page must have title and description
• Headings: Start with H2, maintain proper hierarchy
• Links: All internal links must be relative paths
• Images: All images must be in public/ directory with proper alt text
• Code: All code blocks must specify language

​

Quality Assurance Checklist

## Pre-Commit Checklist
- [ ] All code examples tested and working
- [ ] Screenshots updated and relevant
- [ ] Internal links verified
- [ ] External links checked
- [ ] Mintlify components properly formatted
- [ ] Consistent terminology used
- [ ] Proper heading hierarchy maintained
- [ ] Navigation updated in docs.json
- [ ] Version-specific content in correct directory

​

Troubleshooting Common Issues

​

Mintlify Development Issues

# Mintlify not starting
mintlify install  # Reinstall dependencies

# 404 errors
# Ensure you're in directory with docs.json
# Check navigation paths in docs.json

# Component syntax errors
# Validate MDX syntax
# Check component closing tags

​

Docker Issues

# Container won't start
docker ps -a  # Check container status
docker logs docs-flowxai  # Check logs

# Port conflicts
# Ensure port 3000 is available
# Check for other running containers

​

Content Issues

• Broken Links: Use relative paths, check file existence
• Missing Images: Ensure files are in public/ directory
• Component Errors: Validate Mintlify component syntax
• Navigation Issues: Verify paths in docs.json match file structure

​

Git Workflow and Collaboration

​

Branch Strategy

• main: Production-ready content
• develop: Development branch for new features
• feature/*: Individual feature branches
• hotfix/*: Critical fixes

​

Commit Standards

# Commit message format
git commit -m "docs: add new feature documentation"
git commit -m "fix: correct API endpoint examples"
git commit -m "update: improve setup guide clarity"

​

Pull Request Guidelines

• Include clear description of changes
• Reference related issues or tickets
• Provide testing instructions
• Include screenshots for UI changes
• Update navigation if adding new pages

​

Performance and Optimization

​

Image Optimization

• Use appropriate image formats (WebP, PNG, JPG)
• Optimize file sizes for web delivery
• Include descriptive alt text
• Use consistent image dimensions

​

Content Optimization

• Keep page load times minimal
• Use code splitting for large examples
• Optimize internal linking structure
• Minimize external dependencies

​

SEO Considerations

• Use descriptive, keyword-rich titles
• Write compelling meta descriptions
• Maintain proper heading hierarchy
• Include relevant internal links
• Use semantic HTML structure

​

Deployment and Publishing

​

Automatic Deployment

• Changes to main branch trigger automatic deployment
• GitHub App integration handles the deployment process
• Production site updates within minutes of merge

​

Manual Deployment Verification

• Check production site after deployment
• Verify all links work in production
• Test responsive design on mobile devices
• Validate search functionality

​

Rollback Procedures

• Revert problematic commits if issues arise
• Use Git history to identify breaking changes
• Coordinate with team for urgent fixes
• Document issues and resolutions