A modern, responsive documentation website for satware.ai, built with MkDocs and the beautiful Material for MkDocs theme. This repository serves as the source for the static website deployed to GitHub Pages.

• Clean & Responsive Design: Powered by Material for MkDocs, ensuring a great experience on any device.
• Easy Documentation: Write content in Markdown, and MkDocs handles the rest.
• Local Development with Docker: Simple setup for local development with live-reloading.
• Automated Deployment: Seamless deployment to GitHub Pages via GitHub Actions.

Developing locally is streamlined using Docker, which encapsulates all necessary dependencies.

Prerequisites:

• Docker installed and running on your system.

Steps:

1. Fork the original repository: Fork the satwareAG/satware.ai repository to your GitHub account.

2. Clone your fork:

   git clone https://github.com/YOUR_USERNAME/satware.ai.git
   cd satware.ai

   (Replace YOUR_USERNAME with your GitHub username.)

3. Start the development server:

   ./mkdocs.sh

   This command will build the Docker image (if not already built) and start a local development server. The website will be accessible at http://localhost:8000. Any changes you make to the documentation files (docs/) will automatically trigger a live reload in your browser.

.
├── .github/              # GitHub Actions workflows for CI/CD
│   └── workflows/        # Contains deploy-live.yml and deploy-preview.yml
├── .gitignore            # Specifies intentionally untracked files to ignore
├── .repoinsight/          # Configuration for repository insights (if applicable)
├── docker/               # Docker-related files
│   └── mkdocs-material/  # Dockerfile for the MkDocs Material environment
├── docs/                 # Markdown source files for the documentation
│   ├── index.md          # Homepage content
│   └── ...               # Other documentation pages and assets
├── mkdocs.sh             # Script for local development with Docker
├── mkdocs.yml            # Main MkDocs configuration file
├── overrides/            # Custom theme overrides and assets (e.g., SCSS)
│   └── assets/
│       └── css/
│           └── custom.scss
├── scss_watcher.py       # Python script to watch and compile SCSS
├── tasks.md              # Markdown file for project tasks/notes
└── README.md             # This file

• Static Site Generator: MkDocs
• Theme: Material for MkDocs (v9.6.14)
• Containerization: Docker
• CI/CD: GitHub Actions
• Styling: SCSS (Sass) with pysassc
• Language: Python (v3.13-slim-bullseye in Docker)
• SCSS Watcher: Custom Python script (scss_watcher.py)

The satware.ai website is automatically deployed to GitHub Pages.

Workflow for your fork (for testing/preview):

1. Push to your fork: When you push changes to your fork (https://github.com/YOUR_USERNAME/satware.ai), specifically to the main-mkdocs branch.
2. GitHub Pages Setup: Ensure GitHub Pages is enabled for your fork, building from the gh-pages branch.
3. GitHub Actions Trigger: A GitHub Actions workflow (ci.yml) is triggered.
4. Build & Deploy: This workflow builds the static website using MkDocs and deploys it to the gh-pages branch of your fork.
5. Live Website: The static website becomes available at https://YOUR_USERNAME.github.io/satware.ai/.

Workflow for the main repository (live site):

• Changes merged into the main-mkdocs branch of the original satwareAG/satware.ai repository will trigger the live site deployment to https://satware.ai/.

• SCSS Changes Not Reflecting: Ensure the scss_watcher.py is running correctly within your Docker container. Check the Docker logs for any errors during SCSS compilation. The scss_watcher.py monitors overrides/assets/css/custom.scss and compiles it to docs/assets/css/custom.css.
• Docker Issues: If you encounter issues with the ./mkdocs.sh script, verify that Docker is running and that you have the necessary permissions.

Found a bug, have a feature request, or experiencing issues with the satware.ai website? Please report all issues to our main repository:

🎯 Report Issues Here

When reporting issues, please include:

• Clear description of the problem or feature request
• Steps to reproduce (if applicable)
• Expected behavior vs actual behavior
• Browser/device information (e.g., Chrome 120, Safari on iOS 17)
• Screenshots or error messages (if relevant)
• URL where the issue occurs (if specific to a page)

This helps our team address your concerns quickly and effectively. We appreciate your feedback in making satware.ai better for everyone!

Contributions are welcome! Please see our CONTRIBUTING.md for guidelines.

This project is licensed under the MIT License - see the LICENSE file for details.

For any inquiries or support, please contact info@satware.ai.