Deploy.sh Journey – Dynamic, Idempotent MkDocs Deployment

Date: 2025-11-18

Objective

Create a robust, idempotent deployment script for MkDocs that:

• Dynamically updates the sidebar navigation
• Automatically includes new ChatGPT exports
• Cleans stale HTML to prevent 404 errors
• Builds the MkDocs site into the /site folder
• Reloads Caddy for live updates
• Optionally watches for changes

Key Features Implemented

1. Absolute paths – deploy script can run from anywhere
2. Dynamic navigation – scans docs/ recursively
   • index.md appears as Home
   • Top-level Markdown files (e.g., Tips.md) automatically included
   • Subfolders like Personal, Work, ChatGPT appear as nav groups
3. Idempotent design
   • Running the script multiple times does not duplicate nav entries
   • Cleans /site/ before every build
4. Caddy reload
   • Reloads container automatically after deployment
   • Suppresses harmless Caddyfile warnings due to read-only filesystem
5. Watch mode
   • Optional
   • Monitors docs/ and rebuilds site when Markdown files change

Challenges Overcome

• Handling stale HTML files causing 404s (resolved by auto-clean of /site/)
• Ensuring nav remains idempotent and reflects current docs structure
• Integrating ChatGPT exports dynamically into the sidebar
• Dealing with Caddy running in a read-only Docker container

Usage

```bash

Normal deploy

~/deploy.sh

Enable watch mode

nano ~/deploy.sh

set WATCH_MODE=1

~/deploy.sh