diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
index d4d77d6..e748150 100644
--- a/.github/workflows/deploy-docs.yml
+++ b/.github/workflows/deploy-docs.yml
@@ -2,8 +2,9 @@ name: Deploy MkDocs
 on:
   push:
     branches:
-      - main  # or master, depending on your default branch
-  workflow_dispatch:
+      - main
+      - master
+  workflow_dispatch:  # Allow manual trigger
 
 permissions:
   contents: write
@@ -13,26 +14,49 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+        with:
+          fetch-depth: 0
+      
+      - name: Setup Python
+        uses: actions/setup-python@v4
         with:
           python-version: '3.x'
+          cache: 'pip'  # Enable pip caching
+      
+      - name: Cache MkDocs dependencies
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('docs/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+      
       - name: Install dependencies
         run: |
-          pip install mkdocs-material
-          pip install mkdocs-git-revision-date-localized-plugin
-          pip install mkdocstrings[python]
-      - name: Configure Git
+          python -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
+      
+      - name: Check links
+        run: |
+          mkdocs build --strict
+          
+      - name: Test build
+        run: |
+          mkdocs build
+          if [ ! -d "site" ]; then
+            echo "Build failed - site directory not created"
+            exit 1
+          fi
+      
+      - name: Deploy
         run: |
           git config --global user.name "github-actions[bot]"
           git config --global user.email "github-actions[bot]@users.noreply.github.com"
-      - name: Build docs
-        run: mkdocs build
-      - name: Deploy to GitHub Pages
+          mkdocs gh-deploy --force
+      
+      - name: Verify deployment
         run: |
-          git checkout --orphan gh-pages
-          git rm -rf .
-          mv site/* .
-          rm -rf site
-          git add .
-          git commit -m "docs: Update documentation"
-          git push origin gh-pages --force 
\ No newline at end of file
+          # Wait for GitHub Pages to update
+          sleep 30
+          # Check if the site is accessible
+          curl -s -f -o /dev/null "https://jango-blockchained.github.io/advanced-homeassistant-mcp" || exit 1 
\ No newline at end of file
diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml
deleted file mode 100644
index c2ec3dc..0000000
--- a/.github/workflows/docs-deploy.yml
+++ /dev/null
@@ -1,32 +0,0 @@
-name: Deploy Documentation
-
-on:
-  push:
-    branches:
-      - main
-    paths:
-      - 'docs/**'
-      - 'mkdocs.yml'
-
-permissions:
-  contents: write
-
-jobs:
-  deploy-docs:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: 3.x
-
-      - name: Install dependencies
-        run: |
-          pip install mkdocs-material
-          pip install mkdocs
-
-      - name: Deploy documentation
-        run: mkdocs gh-deploy --force 
\ No newline at end of file
diff --git a/docs/.github/workflows/deploy-docs.yml b/docs/.github/workflows/deploy-docs.yml
deleted file mode 100644
index b9f4e9f..0000000
--- a/docs/.github/workflows/deploy-docs.yml
+++ /dev/null
@@ -1,38 +0,0 @@
-name: Deploy MkDocs
-on:
-  push:
-    branches:
-      - main
-      - master
-
-permissions:
-  contents: write
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      
-      - name: Setup Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: '3.x'
-      
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install mkdocs-material
-          pip install mkdocs-minify-plugin
-          pip install mkdocs-git-revision-date-plugin
-          pip install mkdocs-mkdocstrings
-          pip install mkdocs-social-plugin
-          pip install mkdocs-redirects
-      
-      - name: Deploy
-        run: |
-          git config --global user.name "github-actions[bot]"
-          git config --global user.email "github-actions[bot]@users.noreply.github.com"
-          mkdocs gh-deploy --force 
\ No newline at end of file
diff --git a/docs/deployment.md b/docs/deployment.md
index 26c8f07..3490a9d 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -14,7 +14,7 @@ The documentation is automatically deployed when changes are pushed to the `main
 
 ### GitHub Actions Workflow
 
-The deployment is handled by the workflow in `.github/workflows/deploy-docs.yml`:
+The deployment is handled by the workflow in `.github/workflows/deploy-docs.yml`. This is the single source of truth for documentation deployment:
 
 ```yaml
 name: Deploy MkDocs
@@ -23,6 +23,7 @@ on:
     branches:
       - main
       - master
+  workflow_dispatch:  # Allow manual trigger
 ```
 
 ## Manual Deployment
@@ -30,9 +31,18 @@ on:
 If needed, you can deploy manually using:
 
 ```bash
+# Create a virtual environment
+python -m venv venv
+
+# Activate the virtual environment
+source venv/bin/activate
+
 # Install dependencies
 pip install -r docs/requirements.txt
 
+# Build the documentation
+mkdocs build
+
 # Deploy to GitHub Pages
 mkdocs gh-deploy --force
 ```
@@ -100,4 +110,32 @@ mkdocs-redirects
 
 - Check [GitHub Pages settings](https://github.com/jango-blockchained/advanced-homeassistant-mcp/settings/pages)
 - Monitor build status in Actions tab
-- Verify site accessibility 
\ No newline at end of file
+- Verify site accessibility 
+
+## Workflow Features
+
+### Caching
+The workflow implements caching for Python dependencies to speed up deployments:
+- Pip cache for Python packages
+- MkDocs dependencies cache
+
+### Deployment Checks
+Several checks are performed during deployment:
+1. Link validation with `mkdocs build --strict`
+2. Build verification
+3. Post-deployment site accessibility check
+
+### Manual Triggers
+You can manually trigger deployments using the "workflow_dispatch" event in GitHub Actions.
+
+## Cleanup
+
+To clean up duplicate workflow files, run:
+
+```bash
+# Make the script executable
+chmod +x scripts/cleanup-workflows.sh
+
+# Run the cleanup script
+./scripts/cleanup-workflows.sh
+``` 
\ No newline at end of file
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 0519ecb..4b2f74d 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1 +1,9 @@
- 
\ No newline at end of file
+mkdocs-material>=9.5.0
+mkdocs-minify-plugin>=0.7.1
+mkdocs-git-revision-date-plugin>=0.3.2
+mkdocs-mkdocstrings>=0.24.0
+mkdocs-social-plugin>=0.1.1
+mkdocs-redirects>=1.2.1
+mkdocs-glightbox>=0.3.4
+pillow>=10.0.0
+cairosvg>=2.7.0 
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index 15208da..dca284e 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -51,7 +51,7 @@ plugins:
   - search
   - minify:
       minify_html: true
-  - git-revision-date
+  - git-revision-date-plugin
   - mkdocstrings:
       default_handler: python
   - social