MkDocs Runbook

This runbook walks you through installing the dependencies and setting up the environment for this documentation project.

Steps

🐍 Step 1: Check Python and pip

if ! command -v python3 &> /dev/null; then
  echo "❌ Python 3 is not installed."
  exit 1
fi

if ! command -v pip &> /dev/null; then
  echo "❌ pip is not installed."
  exit 1
fi

echo "✅ Python and pip found."

📦 Step 2: Install Hatch

pip install --upgrade pip hatch

📁 Step 3: Create Hatch Environment

hatch env create docs

🧰 Step 4: Install Node.js and Runme

If Node.js or npm is not available:

if ! command -v node &> /dev/null || ! command -v npm &> /dev/null; then
  echo "🌐 Node.js or npm not found. Installing via nvm..."

  if ! command -v curl &> /dev/null; then
    echo "❌ curl is required to install nvm."
    exit 1
  fi

  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
  export NVM_DIR="$HOME/.nvm"
  [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

  nvm install --lts
  nvm use --lts
fi

📦 Step 5: Install Runme CLI

if ! command -v runme &> /dev/null; then
  echo "📦 Installing Runme CLI globally using npm..."
  npm install runme
else
  echo "✅ Runme is already installed."
fi

✅ You're ready!

Now you can:

# Run MkDocs locally
hatch run docs:serve

# Build the documentation site
hatch run docs:build

# Execute a runbook
runme run docs/runbooks/example-runbook.md

# Build and run with Docker
docker build -t docs-project .
docker run -p 8000:8000 docs-project