docs: Refine MkDocs configuration and GitHub Actions deployment

- Update site name, description, and documentation structure
- Enhance MkDocs theme features and navigation
- Modify documentation navigation to use nested structure
- Improve GitHub Actions workflow with more robust deployment steps
- Add site directory configuration for GitHub Pages

.github/workflows/deploy-docs.yml

@@ -1,38 +1,34 @@
-name: Deploy MkDocs
+name: Deploy Documentation
 on:
   push:
     branches:
-      - main  # or master, depending on your default branch
-  workflow_dispatch:
-
-permissions:
-  contents: write
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
 
 jobs:
   deploy:
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - uses: actions/setup-python@v5
         with:
           python-version: '3.x'
+          cache: 'pip'
       - name: Install dependencies
         run: |
-          pip install mkdocs-material
-          pip install mkdocs-git-revision-date-localized-plugin
-          pip install mkdocstrings[python]
+          python -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
       - name: Configure Git
         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
+      - name: Build and Deploy
         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 
+          mkdocs build --strict
+          mkdocs gh-deploy --force --clean 

.github/workflows/docs-deploy.yml

@@ -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 

docs/.github/workflows/deploy-docs.yml

@@ -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 

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 
+- 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
+``` 

docs/requirements.txt

@@ -1 +1,11 @@
- 
+mkdocs>=1.5.0
+mkdocs-material>=9.0.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
+pymdown-extensions>=10.0 

mkdocs.yml

@@ -1,11 +1,23 @@
-site_name: Advanced Home Assistant MCP
+site_name: MCP Server for Home Assistant
 site_url: https://jango-blockchained.github.io/advanced-homeassistant-mcp
 repo_url: https://github.com/jango-blockchained/advanced-homeassistant-mcp
+site_description: Home Assistant MCP Server Documentation
+# Add this to handle GitHub Pages serving from a subdirectory
+site_dir: site/advanced-homeassistant-mcp
 
 theme:
   name: material
   logo: assets/images/logo.png
   favicon: assets/images/favicon.ico
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.sections
+    - navigation.expand
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.code.copy
   palette:
     - scheme: default
       primary: indigo
@@ -19,18 +31,6 @@ theme:
       toggle:
         icon: material/brightness-4
         name: Switch to light mode
-  features:
-    - navigation.instant
-    - navigation.tracking
-    - navigation.sections
-    - navigation.expand
-    - navigation.top
-    - search.suggest
-    - search.highlight
-    - content.code.copy
-    - content.tabs.link
-    - content.tooltips
-    - toc.integrate
 
 markdown_extensions:
   - pymdownx.highlight:
@@ -51,7 +51,7 @@ plugins:
   - search
   - minify:
       minify_html: true
-  - git-revision-date
+  - git-revision-date-plugin
   - mkdocstrings:
       default_handler: python
   - social
@@ -61,21 +61,14 @@ plugins:
 
 nav:
   - Home: index.md
+  - Getting Started:
+    - Installation: getting-started/installation.md
+    - Quick Start: getting-started/quickstart.md
+  - API Reference: api/index.md
   - Usage: usage.md
   - Configuration:
     - Claude Desktop Config: claude_desktop_config.md
     - Client Config: client_config.md
-  - Getting Started:
-    - Overview: getting-started/index.md
-    - Installation: getting-started/installation.md
-    - Configuration: getting-started/configuration.md
-    - Docker Setup: getting-started/docker.md
-    - Quick Start: getting-started/quickstart.md
-  - API Reference:
-    - Overview: api/index.md
-    - Core API: api/core-api.md
-    - SSE API: api/sse.md
-    - Core Functions: api/core.md
   - Tools:
     - Overview: tools/tools.md
     - Device Management: