194 lines
5.1 KiB
Markdown
194 lines
5.1 KiB
Markdown
# 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).*
|