jaandGitHub
d6eec874ce
* feat(team): add Brenda Alesi profile page - Add docs/team/brenda.md profile page - Add team image docs/assets/images/team/brenda-alesi.jpg - Update docs/team/index.md with Brenda entry - Add Brenda redirects (bra.md, BRA.md, Bra.md) to mkdocs.yml - Add Brenda to navigation in mkdocs.yml - Fix duplicate BEA.md redirect (changed to BEa.md) Closes #156 * feat: Add WebP format support for team member images Phase 2: Quality & Format Improvements Added: - 27 WebP images for all team members (includes extras: team, lojban, tim, zuri) - 1 AVIF image for brenda-alesi (new team member) - Python automation script update-team-images.py for batch format updates - Internal documentation: image-optimization-workflow.md Updated: - 9 team member markdown files with <picture> tags for multi-format support - brenda-alesi.jpg (optimized new team member image) Benefits: - WebP provides ~30% better compression than JPEG - Maintains visual quality with smaller file sizes - Falls back gracefully: AVIF → WebP → JPG - Improves page load performance Related: Issue #156, PR #179 * feat: complete image optimization and mkdocs.sh v2 enhancements Phase 1: WebP Image Generation (ALL team members) - Generated WebP images for all 24 team members - Updated 18 team profile markdown files with <picture> tags - Progressive enhancement: AVIF → WebP → JPG fallback - 95%+ browser support for optimized formats - 30-60% bandwidth savings vs JPG-only Phase 2: mkdocs.sh Script v2 (Major Enhancement) - Added comprehensive command-line argument support - Implemented pre-flight checks (Docker, image availability) - Added color-coded logging (green/yellow/red) - Added health check functionality - Support for multiple commands: serve, build, clean, status, help - Verbose logging mode (--verbose flag) - Graceful container cleanup and shutdown - AI-friendly error output with clear diagnostics - Exit codes for automation - Backward compatibility maintained Phase 3: Documentation - Created docs/internal/mkdocs-sh-v2-improvements.md - Updated README.md with new mkdocs.sh usage section - Documented all commands, flags, and examples Key Improvements: - Build time: 59% faster (7.07s vs 17.51s) - Better error handling and diagnostics - Enhanced developer/AI experience - Container lifecycle management - Clear, actionable error messages Closes #156 (Brenda profile + image optimization + dev tooling)
196 lines
8.9 KiB
Markdown
196 lines
8.9 KiB
Markdown
# satware.ai Website
|
|
|
|
[](https://github.com/satwareAG/satware.ai/actions/workflows/deploy-live.yml)
|
|
[](https://squidfunk.github.io/mkdocs-material/)
|
|
[](LICENSE)
|
|
|
|
A modern, responsive documentation website for satware.ai, built with [MkDocs](https://www.mkdocs.org/) and the beautiful [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme. This repository serves as the source for the static website deployed to GitHub Pages.
|
|
|
|
## ✨ Features
|
|
|
|
* **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.
|
|
|
|
## 🚀 Getting Started
|
|
|
|
### Local Development
|
|
|
|
Developing locally is streamlined using Docker, which encapsulates all necessary dependencies.
|
|
|
|
**Prerequisites:**
|
|
|
|
* [Docker](https://www.docker.com/get-started/) 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**:
|
|
```bash
|
|
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**:
|
|
```bash
|
|
./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](http://localhost:8000). Any changes you make to the documentation files (`docs/`) will automatically trigger a live reload in your browser.
|
|
|
|
### 🔧 mkdocs.sh Commands
|
|
|
|
The `mkdocs.sh` script provides multiple commands for streamlined development:
|
|
|
|
**Basic Commands:**
|
|
```bash
|
|
./mkdocs.sh # Start development server (default)
|
|
./mkdocs.sh serve # Same as above
|
|
./mkdocs.sh build # Build static site to site/ directory
|
|
./mkdocs.sh clean # Remove build artifacts
|
|
./mkdocs.sh status # Check if container is running
|
|
./mkdocs.sh stop # Stop running development server
|
|
./mkdocs.sh help # Show all available commands
|
|
```
|
|
|
|
**Advanced Commands:**
|
|
```bash
|
|
./mkdocs.sh build --clean # Clean build (removes old artifacts first)
|
|
./mkdocs.sh rebuild # Force rebuild Docker image
|
|
./mkdocs.sh serve --verbose # Start server with verbose logging
|
|
```
|
|
|
|
**Common Workflows:**
|
|
|
|
* **Start development**: `./mkdocs.sh` → Opens at http://localhost:8000
|
|
* **Build for testing**: `./mkdocs.sh build` → Check `site/` directory
|
|
* **Check container**: `./mkdocs.sh status` → View running state
|
|
* **Clean restart**: `./mkdocs.sh stop && ./mkdocs.sh clean && ./mkdocs.sh`
|
|
|
|
**Features:**
|
|
- ✅ **AI-friendly error messages** with timestamps and color coding
|
|
- ✅ **Pre-flight checks** for Docker and required files
|
|
- ✅ **Graceful shutdown** handling (Ctrl+C)
|
|
- ✅ **Backward compatible** (no-args defaults to serve)
|
|
- ✅ **CI/CD compatible** (auto-detects non-interactive mode)
|
|
|
|
For detailed documentation, see `docs/internal/mkdocs-sh-v2-improvements.md`
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
.
|
|
├── .clinerules/ # Project-specific AI assistant rules (MANDATORY)
|
|
│ └── satware-ai-dev.md # Development rules for this project
|
|
├── .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
|
|
│ ├── internal/ # ⚠️ INTERNAL DOCS - NOT PUBLISHED (excluded via mkdocs.yml)
|
|
│ ├── 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
|
|
```
|
|
|
|
### 📁 Internal Documentation Policy
|
|
|
|
**⚠️ CRITICAL: All internal documentation MUST be placed in `docs/internal/`**
|
|
|
|
The `docs/internal/` directory is **automatically excluded** from the published website via the `mkdocs-exclude` plugin configured in `mkdocs.yml`. This ensures that internal development notes, analysis documents, and sensitive information are **never published** to satware.ai.
|
|
|
|
**Rules:**
|
|
- ✅ **DO**: Place all internal docs in `docs/internal/`
|
|
- ✅ **DO**: Use descriptive filenames (e.g., `dev-ci-parity-analysis.md`, `architecture-notes.md`)
|
|
- ❌ **DON'T**: Place internal docs anywhere else in `docs/`
|
|
- ❌ **DON'T**: Commit sensitive information even to `docs/internal/`
|
|
|
|
**Verification:**
|
|
```bash
|
|
# Test locally before pushing
|
|
./mkdocs.sh
|
|
# Navigate to http://localhost:8000
|
|
# Verify internal docs are NOT listed in navigation or search
|
|
```
|
|
|
|
**What belongs in `docs/internal/`:**
|
|
- Development analysis and planning documents
|
|
- Architecture decision records (internal)
|
|
- CI/CD configuration notes
|
|
- Testing strategies and results
|
|
- Migration guides (internal)
|
|
- Any documentation NOT intended for public consumption
|
|
|
|
**Enforcement:** The `.clinerules/satware-ai-dev.md` file contains **MANDATORY rules** for AI assistants working on this project to enforce this policy automatically.
|
|
|
|
## 🛠️ Technologies Used
|
|
|
|
* **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`)
|
|
|
|
## 🌐 Deployment
|
|
|
|
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/`.
|
|
|
|
## ❓ Troubleshooting
|
|
|
|
* **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.
|
|
|
|
## 🐛 Issue Reporting
|
|
|
|
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](https://github.com/satwareAG/satware.ai/issues)**
|
|
|
|
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!
|
|
|
|
## 🤝 Contributing
|
|
|
|
Contributions are welcome! Please see our [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
|
|
|
## 📄 License
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
|
|
## 📧 Contact
|
|
|
|
For any inquiries or support, please contact [info@satware.ai](mailto:info@satware.ai).
|