faf199aca7
* feat: Add CONTRIBUTING.md * feat: Add CODE_OF_CONDUCT.md * feat: Add SECURITY.md * feat: Add LICENSE file * feat: Update README.md with improved documentation and project details * fix: Generalize README.md for forking workflow * fix: Correct Project Structure in README.md * fix: Correct Build Status badge URL in README.md * fix: Correct Build Status badge URL to point to original repository's live workflow * fix: Correct License badge URL to point to original repository Co-authored-by: Jane Alesi <ja@satware.ai>
108 lines
5.2 KiB
Markdown
108 lines
5.2 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.
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
.
|
|
├── .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
|
|
```
|
|
|
|
## 🛠️ 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.
|
|
|
|
## 🤝 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).
|