Move around docs

docs/index.md

@@ -25,8 +25,102 @@ Welcome to Seirian & James' homelab documentation! This is a docs site that is b
 ## Quick Start
 
 ```bash
+git clone git@gitea.sjhl.nz:james/homelab-infra.git
+cd homelab-infra
+
+# Set up environment
 cp .env.example .env
-for svc in */; do [ -f "$svc/.env.example" ] && cp "$svc/.env.example" "$svc/.env"; done
+# Edit .env with real values
+
+# Set up service secrets
+for svc in traefik gitea nextcloud qbittorrent jellyfin devbox obsidian; do
+    [ -f "$svc/.env.example" ] && cp "$svc/.env.example" "$svc/.env"
+    # Edit each .env with real secrets
+done
+
+# Create required Docker networks
 docker network create web
+
+# Start everything
 make up
 ```
+
+## Commands
+
+```bash
+make up        # Start all services
+make down      # Stop all services
+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
+
+```
+homelab-infra/
+├── .env.example          # Global env template
+├── Makefile              # Service management
+├── backup.sh             # Restic backup script
+├── .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
+
+- Configs (in Git): this repo
+- Secrets (not in Git): per-service `.env` files
+- Persistent data: `/mnt/storage/docker-data/<service>`
+- Backups: `/mnt/storage/backups`