CLean up site generation

README.md

@@ -29,15 +29,10 @@ make up
 
 | Service | Description | URL |
 |---------|-------------|-----|
-| traefik | Reverse proxy, TLS termination | `dashboard.sjhl.nz` |
-| gitea | Self-hosted Git | `gitea.sjhl.nz` |
-| nextcloud | Cloud storage (AIO) | `nextcloud.sjhl.nz` |
-| qbittorrent | Torrent client (VPN) | Internal only |
-| jellyfin | Media server | `jellyfin.sjhl.nz` |
-| devbox | Dev container | SSH:46573 |
+| gitea | Self-hosted Git | [gitea.sjhl.nz](https://gitea.sjhl.nz) |
+| nextcloud | Cloud storage (AIO) | [nextcloud.sjhl.nz](https://nextcloud.sjhl.nz) |
+| devbox | Dev container | Internal only |
 | obsidian | CouchDB for Obsidian LiveSync | Internal |
-| n8n | Workflow automation (planned) | - |
-| supersync | File sync (planned) | - |
 
 ## Commands
 
@@ -48,9 +43,56 @@ make restart   # Restart all services
 make status    # Show status of all services
 make logs      # Show recent logs
 make backup    # Run Restic backup
+make init-env  # Create missing .env files from templates
+make env-sync  # Rewrite .env files to match templates
 make docs      # Build MkDocs site
 ```
 
+## Documentation
+
+This repo uses **MkDocs** with the **include-markdown** plugin to generate live documentation.
+
+### How it works:
+1. Each service page is auto-generated to include:
+   - `docker-compose.yml` configuration
+   - `Dockerfile` (if exists)
+   - `README.md` (if exists)
+   - `.env.example` for environment variables
+
+2. Files are automatically pulled at build time—changes to service files appear in docs immediately
+
+3. Build docs with:
+   ```bash
+   make docs      # Generate docs and build site
+   make serve-docs # Serve docs locally at http://localhost:8000
+   ```
+
+### Pre-commit Checks
+
+This repo includes a pre-commit hook that syncs .env.example from .env schema.
+
+Behavior:
+- `.env` defines the schema: keys, structure, comments
+- `.env.example` provides defaults and is regenerated from `.env`
+- Keys in `.env.example` are kept only if they exist in `.env`
+- Default values are preserved from `.env.example`
+- New keys from `.env` get `__CHANGEME__` placeholder if not in template
+
+One-time install:
+
+```bash
+uvx pre-commit install
+```
+
+Run manually at any time:
+
+```bash
+uvx pre-commit run --all-files
+make env-sync
+```
+
+If files were updated, re-stage and commit again.
+
 ## Directory Structure
 
 ```
@@ -58,16 +100,13 @@ homelab-infra/
 ├── .env.example          # Global env template
 ├── Makefile              # Service management
 ├── backup.sh             # Restic backup script
-├── traefik/              # Reverse proxy
-├── gitea/                # Git hosting
-├── nextcloud/            # Cloud storage (AIO)
-├── qbittorrent/          # Torrent + VPN stack
-├── jellyfin/             # Media server
-├── devbox/               # Development container
-├── obsidian/             # CouchDB for LiveSync
-├── n8n/                  # Workflow automation
-├── supersync/            # File sync
-└── docs/                 # MkDocs documentation
+├── .pre-commit-config.yaml  # Pre-commit hooks
+├── docs/                 # MkDocs documentation
+├── mkdocs.yml              # MkDocs config
+├── scripts/                # Utility scripts
+└── [service subdirs]/             # All services have their own subdir
+
+
 ```
 
 ## Data Locations
@@ -75,5 +114,4 @@ homelab-infra/
 - Configs (in Git): this repo
 - Secrets (not in Git): per-service `.env` files
 - Persistent data: `/mnt/storage/docker-data/<service>`
-- Media: `/mnt/storage`
 - Backups: `/mnt/storage/backups`