* 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>
This commit is contained in:
@@ -1,81 +1,107 @@
|
||||
# satwareai-mkdocs
|
||||
# satware.ai Website
|
||||
|
||||
A documentation website for satware.ai built with MkDocs and the Material for MkDocs theme.
|
||||
[](https://github.com/satwareAG/satware.ai/actions/workflows/deploy-live.yml)
|
||||
[](https://squidfunk.github.io/mkdocs-material/)
|
||||
[](LICENSE)
|
||||
|
||||
## Overview
|
||||
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.
|
||||
|
||||
This project contains the source files for the satware.ai documentation website. It uses MkDocs as the static site generator and the Material for MkDocs theme for styling and enhanced functionality.
|
||||
## ✨ Features
|
||||
|
||||
## Setup and Installation
|
||||
* **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.
|
||||
|
||||
1. Clone the repository:
|
||||
```bash
|
||||
git clone https://github.com/satware-ag/satwareai-mkdocs.git
|
||||
cd satwareai-mkdocs
|
||||
```
|
||||
## 🚀 Getting Started
|
||||
|
||||
### Local Development
|
||||
|
||||
2. Create and activate a virtual environment:
|
||||
Developing locally is streamlined using Docker, which encapsulates all necessary dependencies.
|
||||
|
||||
```bash
|
||||
python -m venv venv
|
||||
source venv/bin/activate # On Windows: venv\Scripts\activate
|
||||
**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. Install the dependencies:
|
||||
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.
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
### Project Structure
|
||||
|
||||
|
||||
## Development
|
||||
|
||||
To start the development server:
|
||||
|
||||
|
||||
```bash
|
||||
./dev.sh
|
||||
```
|
||||
.
|
||||
├── .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
|
||||
```
|
||||
|
||||
Or manually:
|
||||
## 🛠️ Technologies Used
|
||||
|
||||
```bash
|
||||
mkdocs serve
|
||||
```
|
||||
* **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
|
||||
|
||||
This will start a local development server at [http://127.0.0.1:8000/](http://127.0.0.1:8000/) that automatically reloads when you make changes to the documentation.
|
||||
The `satware.ai` website is automatically deployed to GitHub Pages.
|
||||
|
||||
### SCSS Compilation
|
||||
**Workflow for your fork (for testing/preview):**
|
||||
|
||||
The project uses SCSS for styling. To compile SCSS files to CSS:
|
||||
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/`.
|
||||
|
||||
```bash
|
||||
python compile_scss.py
|
||||
```
|
||||
## ❓ Troubleshooting
|
||||
|
||||
## Building the Site
|
||||
* **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.
|
||||
|
||||
To build the static site:
|
||||
## 🤝 Contributing
|
||||
|
||||
Contributions are welcome! Please see our [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
||||
|
||||
```bash
|
||||
mkdocs build
|
||||
```
|
||||
## 📄 License
|
||||
|
||||
This will create a `site` directory with the built static site.
|
||||
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
||||
|
||||
## 📧 Contact
|
||||
|
||||
## Theme Customization
|
||||
|
||||
The site uses the Material for MkDocs theme with custom overrides located in the `docs/overrides` directory. Additional styling is provided through SCSS files in the `docs/stylesheets` directory.
|
||||
|
||||
## Documentation
|
||||
|
||||
For more information about MkDocs and the Material for MkDocs theme, refer to:
|
||||
|
||||
- [MkDocs Documentation](https://www.mkdocs.org/getting-started/)
|
||||
- [Material for MkDocs Documentation](https://squidfunk.github.io/mkdocs-material/getting-started/)
|
||||
For any inquiries or support, please contact [info@satware.ai](mailto:info@satware.ai).
|
||||
|
||||
Reference in New Issue
Block a user