Merge pull request #81 from weeklydevchat/feature/hot-reloading-in-docker

Enhance Docker configuration for hot reloading with MkDocs

Author: mrbiggred

AGENTS.md

@@ -168,11 +168,24 @@ mkdocs serve
 
 **Setup**:
 ```bash
-# Start development server
+# Start development server with hot reloading
 docker compose up app
 
 # Site available at http://localhost:8000
-# Hot-reloading enabled for development
+```
+
+**Features**:
+- **Hot Reloading**: File changes in `docs/` or `mkdocs.yml` automatically trigger a rebuild and browser refresh
+- **Pip Cache**: Python packages are cached in a Docker volume (`pip-cache`) for faster subsequent starts
+- **Theme Watching**: The `--watch-theme` flag enables detection of theme file changes
+
+**Stopping the Server**:
+```bash
+# Stop containers (preserves pip cache)
+docker compose down
+
+# Stop containers and remove all volumes (clears pip cache)
+docker compose down -v
 ```
 
 ### Testing Changes
@@ -359,8 +372,9 @@ mkdocs gh-deploy --force        # Force deploy (used by CI)
 mkdocs -h                       # Show help
 
 # Docker
-docker compose up app           # Start development server in Docker
-docker compose down             # Stop Docker containers
+docker compose up app           # Start development server with hot reloading
+docker compose down             # Stop containers (preserves pip cache)
+docker compose down -v          # Stop containers and clear pip cache
 
 # Create new post
 ./create_post.sh                # Create post for next Tuesday (bash)

README.md

@@ -54,7 +54,14 @@ This is a static site built with [MkDocs Material](https://squidfunk.github.io/m
 
 2. Open your browser to [http://localhost:8000](http://localhost:8000)
 
-The site will automatically reload when you make changes to the content.
+**Hot Reloading**: The Docker development environment supports hot reloading out of the box. When you edit any file in the `docs/` directory (or `mkdocs.yml`), the site will automatically rebuild and your browser will refresh to show the changes.
+
+**Pip Cache**: Python packages are cached in a Docker volume (`pip-cache`), so subsequent container starts are faster since packages don't need to be re-downloaded.
+
+To stop the server, press `Ctrl+C`. To completely remove containers and volumes:
+```bash
+docker compose down -v
+```
 
 ## Creating Blog Posts
 
@@ -143,8 +150,9 @@ mkdocs build --clean            # Clean build
 mkdocs -h                       # Show help
 
 # Docker
-docker compose up app           # Start development server
+docker compose up app           # Start development server (with hot reloading)
 docker compose down             # Stop containers
+docker compose down -v          # Stop containers and remove volumes (pip cache)
 ```
 
 ## Deployment

docker-compose.yml

@@ -1,14 +1,18 @@
 services:
   app:
     image: python:3.14-slim
-    command: mkdocs serve -a 0.0.0.0:8000
+    command: python -m mkdocs serve -a 0.0.0.0:8000 --watch-theme --livereload
     entrypoint: /app/docker-entrypoint.sh
     working_dir: /app
     ports:
       - 8000:8000
     volumes:
       - .:/app
-      - python-packages:/usr/local/lib/python3.14/site-packages/
+      - pip-cache:/root/.cache/pip
+    environment:
+      - PYTHONUNBUFFERED=1
+    stdin_open: true
+    tty: true
 
 volumes:
-  python-packages:
+  pip-cache: