feat: Set up MkDocs documentation site with Material theme

- Created comprehensive MkDocs configuration with Material theme - Set up organized documentation structure for ALwrity features - Added GitHub Pages deployment workflow - Created initial documentation pages: - Homepage with feature overview - Quick Start guide - Blog Writer and SEO Dashboard feature docs - Comprehensive troubleshooting guide - Configured responsive design with dark/light mode toggle - Added search functionality and navigation - Set up automatic deployment to GitHub Pages The documentation site will be available at https://alwrity.github.io/ALwrity
2025-09-24 16:53:29 +05:30
parent ac307683e0
commit 5bee5c0aa0
9 changed files with 1259 additions and 0 deletions
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,62 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+    paths: ['docs/**', 'docs-site/**', 'mkdocs.yml']
+  pull_request:
+    branches: [main]
+    paths: ['docs/**', 'docs-site/**', 'mkdocs.yml']
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs mkdocs-material
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Build documentation
+        run: |
+          cd docs-site
+          mkdocs build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs-site/site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
--- a/.gitignore
+++ b/.gitignore
@@ -19,6 +19,9 @@ __pycache__/
 **/cache/
 *.cache

+# MkDocs site directory
+docs-site/site/
+
 venv_new
 venv
 # Environment files
--- a/docs-site/README.md
+++ b/docs-site/README.md
@@ -0,0 +1,193 @@
+# ALwrity Documentation Site
+
+This directory contains the MkDocs-based documentation site for ALwrity, an AI-powered digital marketing platform.
+
+## 🚀 Quick Start
+
+### Local Development
+
+1. **Install Dependencies**:
+   ```bash
+   pip install mkdocs mkdocs-material
+   ```
+
+2. **Serve Locally**:
+   ```bash
+   mkdocs serve
+   ```
+   The documentation will be available at `http://127.0.0.1:8000`
+
+3. **Build Site**:
+   ```bash
+   mkdocs build
+   ```
+   The built site will be in the `site/` directory
+
+### GitHub Pages Deployment
+
+The documentation is automatically deployed to GitHub Pages when changes are pushed to the `main` branch. The deployment workflow is configured in `.github/workflows/docs.yml`.
+
+**Live Site**: https://alwrity.github.io/ALwrity
+
+## 📁 Structure
+
+```
+docs-site/
+├── docs/                    # Documentation source files
+│   ├── index.md            # Homepage
+│   ├── getting-started/    # Getting started guides
+│   ├── features/           # Feature documentation
+│   │   ├── blog-writer/    # Blog Writer features
+│   │   ├── seo-dashboard/  # SEO Dashboard features
+│   │   └── ...
+│   ├── guides/             # User guides
+│   ├── api/                # API documentation
+│   ├── development/        # Development guides
+│   ├── reference/          # Reference materials
+│   └── vision/             # Vision and roadmap
+├── mkdocs.yml              # MkDocs configuration
+├── site/                   # Built site (generated)
+└── README.md               # This file
+```
+
+## 🎨 Theme Configuration
+
+The documentation uses the Material theme with the following features:
+
+- **Dark/Light Mode**: Toggle between themes
+- **Search**: Built-in search functionality
+- **Navigation**: Tabbed navigation with sections
+- **Responsive**: Mobile-optimized design
+- **Code Highlighting**: Syntax highlighting for code blocks
+- **Emojis**: Emoji support throughout the documentation
+
+## 📝 Adding Content
+
+### Creating New Pages
+
+1. **Create the Markdown file** in the appropriate directory
+2. **Add to navigation** in `mkdocs.yml`
+3. **Use proper frontmatter** for metadata
+4. **Follow the style guide** for consistency
+
+### Style Guide
+
+- **Headings**: Use proper heading hierarchy (H1 → H2 → H3)
+- **Links**: Use relative links for internal documentation
+- **Code**: Use code blocks with language specification
+- **Images**: Place images in appropriate directories
+- **Metadata**: Add frontmatter for page metadata
+
+### Example Page Structure
+
+```markdown
+# Page Title
+
+Brief description of the page content.
+
+## Section 1
+
+Content for section 1.
+
+### Subsection 1.1
+
+More detailed content.
+
+## Section 2
+
+Content for section 2.
+
+---
+
+*Related: [Link to related page](path/to/page.md)*
+```
+
+## 🔧 Configuration
+
+### mkdocs.yml
+
+The main configuration file includes:
+
+- **Site Information**: Name, description, URL
+- **Theme Settings**: Material theme configuration
+- **Navigation**: Site navigation structure
+- **Plugins**: Search and other plugins
+- **Markdown Extensions**: Enhanced markdown features
+
+### Customization
+
+- **Colors**: Modify the theme palette in `mkdocs.yml`
+- **Fonts**: Change fonts in theme configuration
+- **Icons**: Update icons and social links
+- **Features**: Enable/disable theme features
+
+## 🚀 Deployment
+
+### Automatic Deployment
+
+The documentation is automatically deployed to GitHub Pages when:
+
+1. Changes are pushed to the `main` branch
+2. Files in `docs/`, `docs-site/`, or `mkdocs.yml` are modified
+3. The GitHub Actions workflow runs successfully
+
+### Manual Deployment
+
+```bash
+# Build the site
+mkdocs build
+
+# Deploy to GitHub Pages
+mkdocs gh-deploy
+```
+
+## 📊 Analytics
+
+The documentation site includes:
+
+- **GitHub Analytics**: Built-in GitHub Pages analytics
+- **Search Analytics**: Search query tracking
+- **Performance Monitoring**: Page load times and user behavior
+
+## 🤝 Contributing
+
+### Documentation Guidelines
+
+1. **Write Clearly**: Use clear, concise language
+2. **Be Comprehensive**: Cover all aspects of the topic
+3. **Include Examples**: Provide practical examples
+4. **Update Regularly**: Keep documentation current
+5. **Test Links**: Verify all links work correctly
+
+### Review Process
+
+1. **Create Pull Request**: Submit changes via PR
+2. **Review Content**: Ensure accuracy and clarity
+3. **Test Locally**: Build and test the site locally
+4. **Merge**: Merge after approval
+
+## 📚 Resources
+
+- **MkDocs Documentation**: https://www.mkdocs.org/
+- **Material Theme**: https://squidfunk.github.io/mkdocs-material/
+- **Markdown Guide**: https://www.markdownguide.org/
+- **GitHub Pages**: https://pages.github.com/
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+1. **Build Failures**: Check `mkdocs.yml` syntax
+2. **Missing Pages**: Verify navigation configuration
+3. **Broken Links**: Test all internal and external links
+4. **Theme Issues**: Check theme configuration
+
+### Getting Help
+
+- **GitHub Issues**: Report documentation issues
+- **Community**: Join developer discussions
+- **Documentation**: Check MkDocs and Material theme docs
+
+---
+
+*For more information about ALwrity, visit our [main repository](https://github.com/AJaySi/ALwrity).*
--- a/docs-site/docs/features/blog-writer/overview.md
+++ b/docs-site/docs/features/blog-writer/overview.md
@@ -0,0 +1,167 @@
+# Blog Writer Overview
+
+The ALwrity Blog Writer is a powerful AI-driven content creation tool that helps you generate high-quality, SEO-optimized blog posts with minimal effort.
+
+## Key Features
+
+### 🤖 AI-Powered Content Generation
+- **Topic Research**: Automated research and fact-checking
+- **Content Structure**: Intelligent outline generation
+- **Writing Styles**: Multiple writing styles and tones
+- **SEO Optimization**: Built-in SEO analysis and recommendations
+
+### 📊 Research Integration
+- **Real-time Research**: Access to current information
+- **Source Verification**: Fact-checking and source validation
+- **Trend Analysis**: Current trends and topics
+- **Competitor Analysis**: Content gap identification
+
+### 🎯 SEO Optimization
+- **Keyword Analysis**: Primary and secondary keyword optimization
+- **Meta Tags**: Automatic meta description and title generation
+- **Readability**: Content readability optimization
+- **Internal Linking**: Smart internal linking suggestions
+
+## How It Works
+
+### 1. Content Planning
+```mermaid
+graph TD
+    A[Topic Input] --> B[Research Phase]
+    B --> C[Outline Generation]
+    C --> D[Content Creation]
+    D --> E[SEO Analysis]
+    E --> F[Final Review]
+```
+
+### 2. Research Process
+- **Topic Analysis**: Understanding the subject matter
+- **Keyword Research**: Identifying relevant keywords
+- **Competitor Analysis**: Analyzing top-performing content
+- **Source Gathering**: Collecting reliable information
+
+### 3. Content Generation
+- **Introduction**: Engaging opening paragraphs
+- **Body Content**: Well-structured main content
+- **Conclusion**: Compelling closing statements
+- **Call-to-Action**: Strategic CTAs placement
+
+## Content Types
+
+### Blog Posts
+- **How-to Guides**: Step-by-step tutorials
+- **Listicles**: Numbered list articles
+- **Case Studies**: Real-world examples
+- **Opinion Pieces**: Thought leadership content
+
+### Long-form Content
+- **Comprehensive Guides**: In-depth resources
+- **White Papers**: Professional documents
+- **E-books**: Extended content pieces
+- **Research Reports**: Data-driven content
+
+## SEO Features
+
+### Keyword Optimization
+- **Primary Keywords**: Main topic keywords
+- **Secondary Keywords**: Supporting terms
+- **Long-tail Keywords**: Specific phrases
+- **LSI Keywords**: Semantically related terms
+
+### Content Structure
+- **Headings**: H1, H2, H3 hierarchy
+- **Paragraphs**: Optimal length and structure
+- **Lists**: Bulleted and numbered lists
+- **Images**: Alt text and captions
+
+### Meta Optimization
+- **Title Tags**: SEO-optimized titles
+- **Meta Descriptions**: Compelling descriptions
+- **URL Structure**: Clean, readable URLs
+- **Schema Markup**: Structured data
+
+## Writing Styles
+
+### Professional
+- **Business Content**: Corporate communications
+- **Technical Writing**: Industry-specific content
+- **Academic Style**: Research-based content
+- **Formal Tone**: Professional language
+
+### Conversational
+- **Blog Style**: Casual, engaging tone
+- **Social Media**: Platform-optimized content
+- **Personal Brand**: Authentic voice
+- **Community Content**: Community-focused writing
+
+## Integration Features
+
+### Google Search Console
+- **Performance Data**: Real search performance
+- **Keyword Insights**: Actual search queries
+- **Click-through Rates**: CTR optimization
+- **Search Rankings**: Position tracking
+
+### Analytics Integration
+- **Google Analytics**: Traffic analysis
+- **Content Performance**: Engagement metrics
+- **User Behavior**: Reader interaction data
+- **Conversion Tracking**: Goal completion
+
+## Best Practices
+
+### Content Quality
+1. **Research Thoroughly**: Use multiple sources
+2. **Original Content**: Avoid plagiarism
+3. **Fact-checking**: Verify all information
+4. **Regular Updates**: Keep content current
+
+### SEO Optimization
+1. **Keyword Density**: Natural keyword usage
+2. **Content Length**: Optimal word count
+3. **Internal Linking**: Strategic link placement
+4. **External Links**: Authoritative sources
+
+### User Experience
+1. **Readable Format**: Clear structure
+2. **Visual Elements**: Images and graphics
+3. **Mobile Optimization**: Responsive design
+4. **Loading Speed**: Fast page loads
+
+## Advanced Features
+
+### Content Templates
+- **Industry-specific**: Tailored templates
+- **Content Types**: Various formats
+- **Brand Guidelines**: Consistent styling
+- **Custom Templates**: Personalized formats
+
+### Collaboration Tools
+- **Team Editing**: Multiple contributors
+- **Version Control**: Content history
+- **Comments**: Feedback system
+- **Approval Workflow**: Review process
+
+### Automation
+- **Scheduled Publishing**: Automated posting
+- **Content Calendar**: Planning tools
+- **Social Sharing**: Auto-distribution
+- **Performance Monitoring**: Analytics tracking
+
+## Getting Started
+
+1. **[Research Integration](research.md)** - Set up automated research
+2. **[SEO Analysis](seo-analysis.md)** - Configure SEO optimization
+3. **[Implementation Spec](implementation-spec.md)** - Technical details
+4. **[Best Practices](../guides/best-practices.md)** - Optimization tips
+
+## Related Features
+
+- **[SEO Dashboard](../seo-dashboard/overview.md)** - Comprehensive SEO tools
+- **[Content Strategy](../content-strategy/overview.md)** - Strategic planning
+- **[LinkedIn Writer](../linkedin-writer/overview.md)** - Social content
+- **[AI Features](../ai/assistive-writing.md)** - Advanced AI capabilities
+
+---
+
+*Ready to create amazing blog content? Check out our [Research Integration Guide](research.md) to get started!*
--- a/docs-site/docs/features/seo-dashboard/overview.md
+++ b/docs-site/docs/features/seo-dashboard/overview.md
@@ -0,0 +1,181 @@
+# SEO Dashboard Overview
+
+The ALwrity SEO Dashboard provides comprehensive SEO analysis and optimization tools to help you improve your content's search engine visibility and performance.
+
+## Key Features
+
+### 🔍 Comprehensive SEO Analysis
+- **Content Analysis**: In-depth content evaluation
+- **Keyword Optimization**: Keyword density and placement
+- **Readability Assessment**: Content readability scoring
+- **Technical SEO**: Meta tags, headings, and structure
+
+### 📊 Google Search Console Integration
+- **Real Performance Data**: Actual search performance metrics
+- **Keyword Insights**: Top-performing search queries
+- **Click-through Rates**: CTR analysis and optimization
+- **Search Rankings**: Position tracking and monitoring
+
+### 🎯 Metadata Generation
+- **Title Tags**: SEO-optimized page titles
+- **Meta Descriptions**: Compelling meta descriptions
+- **Schema Markup**: Structured data implementation
+- **Open Graph**: Social media optimization
+
+## Dashboard Components
+
+### 1. Content Analysis Panel
+```mermaid
+graph TD
+    A[Content Input] --> B[SEO Analysis]
+    B --> C[Keyword Analysis]
+    B --> D[Readability Check]
+    B --> E[Structure Review]
+    C --> F[Optimization Suggestions]
+    D --> F
+    E --> F
+```
+
+### 2. Performance Metrics
+- **Search Visibility**: Overall search performance
+- **Keyword Rankings**: Position tracking
+- **Traffic Analysis**: Organic traffic insights
+- **Conversion Rates**: Goal completion tracking
+
+### 3. Optimization Tools
+- **Keyword Suggestions**: Related keyword recommendations
+- **Content Gaps**: Missing content opportunities
+- **Competitor Analysis**: Competitive insights
+- **Technical Issues**: SEO problem identification
+
+## SEO Analysis Features
+
+### Content Optimization
+- **Keyword Density**: Optimal keyword usage
+- **Content Length**: Word count analysis
+- **Heading Structure**: H1-H6 hierarchy
+- **Internal Linking**: Link optimization
+
+### Technical SEO
+- **Page Speed**: Loading time optimization
+- **Mobile Optimization**: Responsive design check
+- **URL Structure**: Clean, SEO-friendly URLs
+- **Image Optimization**: Alt text and compression
+
+### On-Page SEO
+- **Title Tag Optimization**: Compelling, keyword-rich titles
+- **Meta Description**: Engaging descriptions
+- **Header Tags**: Proper heading structure
+- **Content Quality**: Originality and relevance
+
+## Google Search Console Integration
+
+### Setup Process
+1. **Authentication**: Connect your GSC account
+2. **Property Selection**: Choose your website
+3. **Data Sync**: Import performance data
+4. **Real-time Updates**: Live data integration
+
+### Available Data
+- **Search Queries**: Top search terms
+- **Click Data**: Click-through rates
+- **Impression Data**: Search visibility
+- **Position Data**: Average rankings
+
+### Performance Insights
+- **Top Pages**: Best-performing content
+- **Keyword Opportunities**: Untapped keywords
+- **Content Gaps**: Missing content areas
+- **Technical Issues**: SEO problems
+
+## Metadata Generation
+
+### Title Tag Optimization
+- **Length Optimization**: 50-60 character limit
+- **Keyword Placement**: Primary keyword positioning
+- **Brand Integration**: Consistent branding
+- **Click-through Optimization**: Compelling titles
+
+### Meta Description Creation
+- **Length Guidelines**: 150-160 characters
+- **Call-to-Action**: Compelling CTAs
+- **Keyword Integration**: Natural keyword usage
+- **Value Proposition**: Clear benefits
+
+### Schema Markup
+- **Article Schema**: Content structure
+- **Organization Schema**: Business information
+- **Breadcrumb Schema**: Navigation structure
+- **FAQ Schema**: Question-answer format
+
+## Advanced Features
+
+### Competitor Analysis
+- **Content Comparison**: Competitive content analysis
+- **Keyword Gap Analysis**: Missing keyword opportunities
+- **Performance Benchmarking**: Competitive performance
+- **Content Strategy**: Strategic recommendations
+
+### Content Planning
+- **Keyword Research**: Comprehensive keyword analysis
+- **Content Calendar**: SEO-optimized publishing schedule
+- **Topic Clusters**: Content pillar strategy
+- **Internal Linking**: Strategic link planning
+
+### Performance Monitoring
+- **Ranking Tracking**: Keyword position monitoring
+- **Traffic Analysis**: Organic traffic insights
+- **Conversion Tracking**: Goal completion analysis
+- **Alert System**: Performance change notifications
+
+## Integration Capabilities
+
+### Content Management
+- **WordPress Integration**: Direct publishing
+- **CMS Integration**: Various platform support
+- **API Access**: Custom integrations
+- **Bulk Operations**: Mass content optimization
+
+### Analytics Integration
+- **Google Analytics**: Traffic data integration
+- **Custom Analytics**: Proprietary tracking
+- **Conversion Tracking**: Goal monitoring
+- **ROI Analysis**: Performance measurement
+
+## Best Practices
+
+### SEO Optimization
+1. **Keyword Research**: Comprehensive keyword analysis
+2. **Content Quality**: High-quality, original content
+3. **Technical SEO**: Proper site structure
+4. **User Experience**: Mobile-friendly design
+
+### Performance Monitoring
+1. **Regular Analysis**: Consistent SEO audits
+2. **Data Tracking**: Performance monitoring
+3. **Optimization**: Continuous improvement
+4. **Reporting**: Regular performance reports
+
+### Content Strategy
+1. **Keyword Strategy**: Strategic keyword targeting
+2. **Content Planning**: SEO-optimized content calendar
+3. **Internal Linking**: Strategic link structure
+4. **Content Updates**: Regular content refresh
+
+## Getting Started
+
+1. **[GSC Integration](gsc-integration.md)** - Set up Google Search Console
+2. **[Metadata Generation](metadata.md)** - Configure meta tag generation
+3. **[Design Document](design-document.md)** - Technical specifications
+4. **[Best Practices](../guides/best-practices.md)** - Optimization tips
+
+## Related Features
+
+- **[Blog Writer](../blog-writer/overview.md)** - Content creation with SEO
+- **[Content Strategy](../content-strategy/overview.md)** - Strategic planning
+- **[AI Features](../ai/grounding-ui.md)** - Advanced AI capabilities
+- **[API Reference](../../api/overview.md)** - Technical integration
+
+---
+
+*Ready to optimize your SEO? Check out our [GSC Integration Guide](gsc-integration.md) to get started!*
--- a/docs-site/docs/getting-started/quick-start.md
+++ b/docs-site/docs/getting-started/quick-start.md
@@ -0,0 +1,131 @@
+# Quick Start Guide
+
+Get up and running with ALwrity in just a few minutes! This guide will help you set up the platform and create your first AI-generated content.
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+- **Python 3.10+** installed on your system
+- **Node.js 18+** for the frontend
+- **API Keys** for AI services (Gemini, OpenAI, etc.)
+- **Git** for version control
+
+## Installation
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/AJaySi/ALwrity.git
+cd ALwrity
+```
+
+### 2. Backend Setup
+
+```bash
+cd backend
+pip install -r requirements.txt
+```
+
+### 3. Frontend Setup
+
+```bash
+cd frontend
+npm install
+```
+
+## Configuration
+
+### 1. Environment Variables
+
+Create a `.env` file in the backend directory:
+
+```bash
+# AI Service API Keys
+GEMINI_API_KEY=your_gemini_api_key
+OPENAI_API_KEY=your_openai_api_key
+ANTHROPIC_API_KEY=your_anthropic_api_key
+
+# Database
+DATABASE_URL=sqlite:///./alwrity.db
+
+# Security
+SECRET_KEY=your_secret_key
+```
+
+### 2. Frontend Configuration
+
+Create a `.env` file in the frontend directory:
+
+```bash
+REACT_APP_API_URL=http://localhost:8000
+REACT_APP_CLERK_PUBLISHABLE_KEY=your_clerk_key
+REACT_APP_COPILOT_API_KEY=your_copilot_key
+```
+
+## Running the Application
+
+### 1. Start the Backend
+
+```bash
+cd backend
+python start_alwrity_backend.py
+```
+
+The backend will be available at `http://localhost:8000`
+
+### 2. Start the Frontend
+
+```bash
+cd frontend
+npm start
+```
+
+The frontend will be available at `http://localhost:3000`
+
+## Your First Content
+
+### 1. Access the Dashboard
+
+Navigate to `http://localhost:3000` and complete the onboarding process.
+
+### 2. Create a Blog Post
+
+1. Go to **Blog Writer**
+2. Enter your topic or keyword
+3. Click **Generate Content**
+4. Review and edit the generated content
+5. Use the **SEO Analysis** feature to optimize
+
+### 3. LinkedIn Content
+
+1. Navigate to **LinkedIn Writer**
+2. Select content type (post, article, carousel)
+3. Provide your topic and target audience
+4. Generate and customize your content
+
+## Next Steps
+
+- **[Configuration Guide](configuration.md)** - Advanced configuration options
+- **[First Steps](first-steps.md)** - Detailed walkthrough of key features
+- **[API Reference](../api/overview.md)** - Integrate with your applications
+- **[Best Practices](../guides/best-practices.md)** - Optimize your content strategy
+
+## Troubleshooting
+
+If you encounter any issues:
+
+1. Check the [Troubleshooting Guide](../guides/troubleshooting.md)
+2. Verify your API keys are correctly set
+3. Ensure all dependencies are installed
+4. Check the console for error messages
+
+## Need Help?
+
+- **GitHub Issues**: [Report bugs and request features](https://github.com/AJaySi/ALwrity/issues)
+- **Documentation**: Browse our comprehensive guides
+- **Community**: Join our developer community
+
+---
+
+*Ready to create amazing content? Check out our [First Steps Guide](first-steps.md) for a detailed walkthrough!*
--- a/docs-site/docs/guides/troubleshooting.md
+++ b/docs-site/docs/guides/troubleshooting.md
@@ -0,0 +1,340 @@
+# Troubleshooting Guide
+
+This guide helps you resolve common issues with ALwrity. If you don't find your issue here, please check our [GitHub Issues](https://github.com/AJaySi/ALwrity/issues) or create a new one.
+
+## Common Issues
+
+### Backend Issues
+
+#### Server Won't Start
+**Symptoms**: Backend server fails to start or crashes immediately
+
+**Solutions**:
+1. **Check Python Version**:
+   ```bash
+   python --version
+   # Should be 3.10 or higher
+   ```
+
+2. **Verify Dependencies**:
+   ```bash
+   cd backend
+   pip install -r requirements.txt
+   ```
+
+3. **Check Port Availability**:
+   ```bash
+   # Check if port 8000 is in use
+   netstat -an | findstr :8000
+   ```
+
+4. **Environment Variables**:
+   ```bash
+   # Ensure .env file exists with required keys
+   GEMINI_API_KEY=your_key_here
+   OPENAI_API_KEY=your_key_here
+   ```
+
+#### Database Connection Errors
+**Symptoms**: Database connection failures or SQL errors
+
+**Solutions**:
+1. **Check Database File**:
+   ```bash
+   # Ensure database file exists
+   ls -la backend/alwrity.db
+   ```
+
+2. **Reset Database**:
+   ```bash
+   cd backend
+   rm alwrity.db
+   python -c "from services.database import initialize_database; initialize_database()"
+   ```
+
+3. **Check Permissions**:
+   ```bash
+   # Ensure write permissions
+   chmod 664 backend/alwrity.db
+   ```
+
+#### API Key Issues
+**Symptoms**: 401/403 errors, "Invalid API key" messages
+
+**Solutions**:
+1. **Verify API Keys**:
+   ```bash
+   # Check .env file
+   cat backend/.env | grep API_KEY
+   ```
+
+2. **Test API Keys**:
+   ```bash
+   # Test Gemini API
+   curl -H "Authorization: Bearer $GEMINI_API_KEY" \
+        https://generativelanguage.googleapis.com/v1/models
+   ```
+
+3. **Check Key Format**:
+   - Gemini: Should start with `AIza...`
+   - OpenAI: Should start with `sk-...`
+   - Anthropic: Should start with `sk-ant-...`
+
+### Frontend Issues
+
+#### Build Failures
+**Symptoms**: `npm start` fails or build errors
+
+**Solutions**:
+1. **Clear Cache**:
+   ```bash
+   cd frontend
+   npm cache clean --force
+   rm -rf node_modules package-lock.json
+   npm install
+   ```
+
+2. **Check Node Version**:
+   ```bash
+   node --version
+   # Should be 18 or higher
+   ```
+
+3. **Environment Variables**:
+   ```bash
+   # Check frontend .env file
+   REACT_APP_API_URL=http://localhost:8000
+   REACT_APP_CLERK_PUBLISHABLE_KEY=your_key
+   ```
+
+#### Connection Issues
+**Symptoms**: Frontend can't connect to backend, CORS errors
+
+**Solutions**:
+1. **Check Backend Status**:
+   ```bash
+   curl http://localhost:8000/health
+   ```
+
+2. **Verify CORS Settings**:
+   ```python
+   # In backend/app.py
+   app.add_middleware(
+       CORSMiddleware,
+       allow_origins=["http://localhost:3000"],
+       allow_credentials=True,
+       allow_methods=["*"],
+       allow_headers=["*"],
+   )
+   ```
+
+3. **Check Firewall**:
+   ```bash
+   # Windows
+   netsh advfirewall firewall show rule name="Python"
+   ```
+
+### Content Generation Issues
+
+#### SEO Analysis Not Working
+**Symptoms**: SEO analysis fails or returns 422 errors
+
+**Solutions**:
+1. **Check API Endpoints**:
+   ```bash
+   # Test SEO endpoint
+   curl -X POST http://localhost:8000/api/blog-writer/seo/analyze \
+        -H "Content-Type: application/json" \
+        -d '{"content": "test content"}'
+   ```
+
+2. **Verify Request Format**:
+   ```javascript
+   // Ensure proper request structure
+   const requestData = {
+     content: blogContent,
+     researchData: researchData,
+     user_id: userId
+   };
+   ```
+
+3. **Check Backend Logs**:
+   ```bash
+   # Look for error messages in backend console
+   ```
+
+#### Content Generation Failures
+**Symptoms**: AI content generation fails or returns errors
+
+**Solutions**:
+1. **Check API Quotas**:
+   - Verify API key has sufficient credits
+   - Check rate limits and usage
+
+2. **Test API Connectivity**:
+   ```bash
+   # Test Gemini API
+   curl -X POST \
+     -H "Authorization: Bearer $GEMINI_API_KEY" \
+     -H "Content-Type: application/json" \
+     https://generativelanguage.googleapis.com/v1/models/gemini-pro:generateContent
+   ```
+
+3. **Check Request Size**:
+   - Ensure content isn't too long
+   - Break large requests into smaller chunks
+
+### Authentication Issues
+
+#### Clerk Authentication Problems
+**Symptoms**: Login failures, authentication errors
+
+**Solutions**:
+1. **Verify Clerk Keys**:
+   ```bash
+   # Check frontend .env
+   REACT_APP_CLERK_PUBLISHABLE_KEY=pk_test_...
+   ```
+
+2. **Check Clerk Dashboard**:
+   - Verify domain configuration
+   - Check user permissions
+   - Review authentication settings
+
+3. **Clear Browser Cache**:
+   ```bash
+   # Clear localStorage and cookies
+   ```
+
+### Performance Issues
+
+#### Slow Content Generation
+**Symptoms**: Long response times, timeouts
+
+**Solutions**:
+1. **Check API Response Times**:
+   ```bash
+   # Monitor API performance
+   curl -w "@curl-format.txt" -o /dev/null -s http://localhost:8000/api/blog-writer
+   ```
+
+2. **Optimize Request Size**:
+   - Reduce content length
+   - Use streaming for large responses
+   - Implement caching
+
+3. **Check System Resources**:
+   ```bash
+   # Monitor CPU and memory usage
+   top
+   ```
+
+#### Database Performance
+**Symptoms**: Slow database queries, high response times
+
+**Solutions**:
+1. **Optimize Queries**:
+   ```python
+   # Add database indexes
+   # Use connection pooling
+   # Implement query caching
+   ```
+
+2. **Check Database Size**:
+   ```bash
+   # Monitor database file size
+   ls -lh backend/alwrity.db
+   ```
+
+## Debugging Tools
+
+### Backend Debugging
+```python
+# Enable debug logging
+import logging
+logging.basicConfig(level=logging.DEBUG)
+
+# Add debug prints
+print(f"Debug: {variable_name}")
+```
+
+### Frontend Debugging
+```javascript
+// Enable React DevTools
+// Add console.log statements
+console.log('Debug:', data);
+
+// Use React Developer Tools
+// Check Network tab for API calls
+```
+
+### API Testing
+```bash
+# Test API endpoints
+curl -X GET http://localhost:8000/health
+curl -X POST http://localhost:8000/api/blog-writer \
+     -H "Content-Type: application/json" \
+     -d '{"topic": "test"}'
+```
+
+## Log Analysis
+
+### Backend Logs
+```bash
+# Check backend console output
+# Look for error messages
+# Monitor API response times
+```
+
+### Frontend Logs
+```bash
+# Check browser console
+# Monitor network requests
+# Review error messages
+```
+
+### Database Logs
+```bash
+# Check database queries
+# Monitor connection issues
+# Review performance metrics
+```
+
+## Getting Help
+
+### Self-Service Resources
+1. **Documentation**: Check relevant guides
+2. **GitHub Issues**: Search existing issues
+3. **Community**: Join discussions
+4. **FAQ**: Common questions and answers
+
+### Reporting Issues
+When reporting issues, include:
+1. **Error Messages**: Complete error text
+2. **Steps to Reproduce**: Detailed steps
+3. **Environment**: OS, Python version, Node version
+4. **Logs**: Relevant log entries
+5. **Screenshots**: Visual error evidence
+
+### Contact Information
+- **GitHub Issues**: [Create an issue](https://github.com/AJaySi/ALwrity/issues)
+- **Documentation**: Browse guides and API reference
+- **Community**: Join developer discussions
+
+## Prevention Tips
+
+### Regular Maintenance
+1. **Update Dependencies**: Keep packages current
+2. **Monitor Performance**: Regular performance checks
+3. **Backup Data**: Regular database backups
+4. **Security Updates**: Keep system secure
+
+### Best Practices
+1. **Environment Management**: Use virtual environments
+2. **Configuration Management**: Proper .env files
+3. **Error Handling**: Implement proper error handling
+4. **Monitoring**: Set up performance monitoring
+
+---
+
+*Still having issues? Check our [GitHub Issues](https://github.com/AJaySi/ALwrity/issues) or create a new one with detailed information about your problem.*
--- a/docs-site/docs/index.md
+++ b/docs-site/docs/index.md
@@ -0,0 +1,74 @@
+# Welcome to ALwrity Documentation
+
+<div class="grid cards" markdown>
+
+-   :material-rocket-launch:{ .lg .middle } **Quick Start**
+
+    ---
+
+    Get up and running with ALwrity in minutes
+
+    [:octicons-arrow-right-24: Quick Start](getting-started/quick-start.md)
+
+-   :material-robot:{ .lg .middle } **AI Features**
+
+    ---
+
+    Explore our AI-powered content generation capabilities
+
+    [:octicons-arrow-right-24: AI Features](features/ai/assistive-writing.md)
+
+-   :material-chart-line:{ .lg .middle } **SEO Dashboard**
+
+    ---
+
+    Comprehensive SEO analysis and optimization tools
+
+    [:octicons-arrow-right-24: SEO Dashboard](features/seo-dashboard/overview.md)
+
+-   :material-pencil:{ .lg .middle } **Content Writers**
+
+    ---
+
+    Blog, LinkedIn, and Facebook content generation
+
+    [:octicons-arrow-right-24: Content Writers](features/blog-writer/overview.md)
+
+</div>
+
+## What is ALwrity?
+
+ALwrity is an AI-powered digital marketing platform that revolutionizes content creation and SEO optimization. Our platform combines advanced AI technology with comprehensive marketing tools to help businesses create high-quality, SEO-optimized content at scale.
+
+### Key Features
+
+- **🤖 AI-Powered Content Generation**: Create blog posts, LinkedIn content, and Facebook posts with advanced AI
+- **📊 SEO Dashboard**: Comprehensive SEO analysis with Google Search Console integration
+- **🎯 Content Strategy**: AI-driven persona generation and content planning
+- **🔍 Research Integration**: Automated research and fact-checking capabilities
+- **📈 Performance Analytics**: Track content performance and optimize strategies
+- **🔒 Enterprise Security**: Secure, scalable platform for teams of all sizes
+
+### Getting Started
+
+1. **[Installation](getting-started/installation.md)** - Set up ALwrity on your system
+2. **[Configuration](getting-started/configuration.md)** - Configure API keys and settings
+3. **[First Steps](getting-started/first-steps.md)** - Create your first content piece
+4. **[Best Practices](guides/best-practices.md)** - Learn optimization techniques
+
+### Popular Guides
+
+- [Troubleshooting Common Issues](guides/troubleshooting.md)
+- [API Integration Guide](api/overview.md)
+- [Content Strategy Best Practices](features/content-strategy/overview.md)
+- [SEO Optimization Tips](features/seo-dashboard/overview.md)
+
+### Community & Support
+
+- **GitHub**: [Report issues and contribute](https://github.com/AJaySi/ALwrity)
+- **Documentation**: Comprehensive guides and API reference
+- **Community**: Join our developer community
+
+---
+
+*Ready to transform your content creation workflow? Start with our [Quick Start Guide](getting-started/quick-start.md) or explore our [AI Features](features/ai/assistive-writing.md).*
--- a/docs-site/mkdocs.yml
+++ b/docs-site/mkdocs.yml
@@ -0,0 +1,108 @@
+site_name: ALwrity Documentation
+site_description: AI-Powered Digital Marketing Platform - Complete Documentation
+site_url: https://alwrity.github.io/ALwrity
+repo_url: https://github.com/AJaySi/ALwrity
+repo_name: AJaySi/ALwrity
+edit_uri: edit/main/docs-site/docs/
+
+# Copyright
+copyright: Copyright &copy; 2024 ALwrity Team
+
+# Configuration
+theme:
+  name: material
+  palette:
+    # Light mode
+    - scheme: default
+      primary: blue
+      accent: light blue
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    # Dark mode
+    - scheme: slate
+      primary: blue
+      accent: light blue
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.expand
+    - navigation.path
+    - navigation.top
+    - search.highlight
+    - search.share
+    - search.suggest
+    - content.code.copy
+    - content.code.annotate
+    - content.action.edit
+    - content.action.view
+  font:
+    text: Roboto
+    code: Roboto Mono
+  icon:
+    repo: fontawesome/brands/github
+    edit: material/pencil
+    view: material/eye
+
+# Plugins
+plugins:
+  - search:
+      lang: en
+
+# Markdown extensions
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+      combine_header_slug: true
+      slugify: !!python/object/apply:pymdownx.slugs.slugify
+        kwds:
+          case: lower
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - attr_list
+  - md_in_html
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - tables
+  - toc:
+      permalink: true
+      title: On this page
+
+# Extra configuration
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/AJaySi/ALwrity
+
+# Navigation structure
+nav:
+  - Home: index.md
+  - Getting Started:
+    - Quick Start: getting-started/quick-start.md
+  - Features:
+    - Blog Writer:
+      - Overview: features/blog-writer/overview.md
+    - SEO Dashboard:
+      - Overview: features/seo-dashboard/overview.md
+  - Guides:
+    - Troubleshooting: guides/troubleshooting.md