# 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).*