ALwrity/docs-site

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:

   pip install mkdocs mkdocs-material
   

2. Serve Locally:

   mkdocs serve
   

   The documentation will be available at http://127.0.0.1:8000

3. Build Site:

   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

# 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

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