docs: Enhance MkDocs configuration with advanced features and styling

- Upgrade MkDocs Material theme with modern navigation and UI features
- Add comprehensive markdown extensions and plugin configurations
- Introduce new JavaScript and CSS for improved documentation experience
- Update documentation requirements with latest plugin versions
- Implement dark mode enhancements and code block improvements
- Expand navigation structure and add new documentation sections

.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 

.gitignore

@@ -31,7 +31,7 @@ wheels/
 venv/
 ENV/
 env/
-
+.venv/
 # Logs
 logs
 *.log
@@ -89,4 +89,6 @@ __pycache__/
 *.py[cod]
 *$py.class
 
-models/
+models/
+
+*.code-workspace

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/api/index.md

@@ -237,6 +237,6 @@ The current API version is v1. Include the version in the URL:
 
 The Advanced Home Assistant MCP provides several APIs for integration and automation:
 
-- [Core API](core-api.md) - Primary interface for system control
+- [Core API](core.md) - Primary interface for system control
 - [SSE API](sse.md) - Server-Sent Events for real-time updates
 - [Core Functions](core.md) - Essential system functions 

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/javascripts/extra.js

@@ -0,0 +1,62 @@
+// Dark mode handling
+document.addEventListener('DOMContentLoaded', function () {
+    // Check for saved dark mode preference
+    const darkMode = localStorage.getItem('darkMode');
+    if (darkMode === 'true') {
+        document.body.classList.add('dark-mode');
+    }
+});
+
+// Smooth scrolling for anchor links
+document.querySelectorAll('a[href^="#"]').forEach(anchor => {
+    anchor.addEventListener('click', function (e) {
+        e.preventDefault();
+        document.querySelector(this.getAttribute('href')).scrollIntoView({
+            behavior: 'smooth'
+        });
+    });
+});
+
+// Add copy button to code blocks
+document.querySelectorAll('pre code').forEach((block) => {
+    const button = document.createElement('button');
+    button.className = 'copy-button';
+    button.textContent = 'Copy';
+
+    button.addEventListener('click', async () => {
+        await navigator.clipboard.writeText(block.textContent);
+        button.textContent = 'Copied!';
+        setTimeout(() => {
+            button.textContent = 'Copy';
+        }, 2000);
+    });
+
+    const pre = block.parentNode;
+    pre.insertBefore(button, block);
+});
+
+// Add version selector handling
+const versionSelector = document.querySelector('.version-selector');
+if (versionSelector) {
+    versionSelector.addEventListener('change', (e) => {
+        const version = e.target.value;
+        window.location.href = `/${version}/`;
+    });
+}
+
+// Add feedback handling
+document.querySelectorAll('.feedback-button').forEach(button => {
+    button.addEventListener('click', function () {
+        const feedback = this.getAttribute('data-feedback');
+        // Send feedback to analytics
+        if (typeof gtag !== 'undefined') {
+            gtag('event', 'feedback', {
+                'event_category': 'Documentation',
+                'event_label': feedback
+            });
+        }
+        // Show thank you message
+        this.textContent = 'Thank you!';
+        this.disabled = true;
+    });
+}); 

docs/javascripts/mathjax.js

@@ -0,0 +1,12 @@
+window.MathJax = {
+    tex: {
+        inlineMath: [["\\(", "\\)"]],
+        displayMath: [["\\[", "\\]"]],
+        processEscapes: true,
+        processEnvironments: true
+    },
+    options: {
+        ignoreHtmlClass: ".*|",
+        processHtmlClass: "arithmatex"
+    }
+}; 

docs/requirements.txt

@@ -1 +1,45 @@
- 
+# Core
+mkdocs>=1.5.3
+mkdocs-material>=9.5.3
+
+# Enhanced Functionality
+mkdocs-minify-plugin>=0.7.1
+mkdocs-git-revision-date-localized-plugin>=1.2.1
+mkdocs-glightbox>=0.3.4
+mkdocs-optimize>=0.1.1
+mkdocs-git-authors-plugin>=0.7.2
+mkdocs-git-committers-plugin>=0.2.3
+mkdocs-static-i18n>=1.2.0
+mkdocs-awesome-pages-plugin>=2.9.2
+mkdocs-redirects>=1.2.1
+mkdocs-include-markdown-plugin>=6.0.4
+mkdocs-macros-plugin>=1.0.4
+mkdocs-meta-descriptions-plugin>=3.0.0
+mkdocs-print-site-plugin>=2.3.6
+mkdocs-pdf-export-plugin>=0.5.10
+mkdocs-with-pdf>=0.9.3
+
+# Code Documentation
+mkdocstrings>=0.24.0
+mkdocstrings-python>=1.7.5
+
+# Markdown Extensions
+pymdown-extensions>=10.5
+markdown>=3.5.1
+mdx_truly_sane_lists>=1.3
+pygments>=2.17.2
+
+# Math Support
+python-markdown-math>=0.8
+
+# Diagrams
+plantuml-markdown>=3.9.2
+mkdocs-mermaid2-plugin>=1.1.1
+
+# Search Enhancements
+mkdocs-material[imaging]>=9.5.3
+pillow>=10.2.0
+cairosvg>=2.7.1
+
+# Development Tools
+mike>=2.0.0  # For version management 

docs/stylesheets/extra.css

@@ -0,0 +1,164 @@
+/* Modern Dark Theme Enhancements */
+[data-md-color-scheme="slate"] {
+    --md-default-bg-color: #1a1b26;
+    --md-default-fg-color: #a9b1d6;
+    --md-default-fg-color--light: #a9b1d6;
+    --md-default-fg-color--lighter: #787c99;
+    --md-default-fg-color--lightest: #4e5173;
+    --md-primary-fg-color: #7aa2f7;
+    --md-primary-fg-color--light: #7dcfff;
+    --md-primary-fg-color--dark: #2ac3de;
+    --md-accent-fg-color: #bb9af7;
+    --md-accent-fg-color--transparent: #bb9af722;
+    --md-accent-bg-color: #1a1b26;
+    --md-accent-bg-color--light: #24283b;
+}
+
+/* Code Blocks */
+.highlight pre {
+    background-color: #24283b !important;
+    border-radius: 6px;
+    padding: 1em;
+    margin: 1em 0;
+    overflow: auto;
+}
+
+.highlight code {
+    font-family: 'Roboto Mono', monospace;
+    font-size: 0.9em;
+}
+
+/* Copy Button */
+.copy-button {
+    position: absolute;
+    right: 0.5em;
+    top: 0.5em;
+    padding: 0.4em 0.8em;
+    background-color: var(--md-accent-bg-color--light);
+    border: 1px solid var(--md-accent-fg-color--transparent);
+    border-radius: 4px;
+    color: var(--md-default-fg-color);
+    font-size: 0.8em;
+    cursor: pointer;
+    transition: all 0.2s ease;
+}
+
+.copy-button:hover {
+    background-color: var(--md-accent-fg-color--transparent);
+    border-color: var(--md-accent-fg-color);
+}
+
+/* Navigation Enhancements */
+.md-nav {
+    font-size: 0.9rem;
+}
+
+.md-nav__link {
+    padding: 0.4rem 0;
+    transition: color 0.2s ease;
+}
+
+.md-nav__link:hover {
+    color: var(--md-primary-fg-color) !important;
+}
+
+/* Tabs */
+.md-tabs__link {
+    opacity: 0.8;
+    transition: opacity 0.2s ease;
+}
+
+.md-tabs__link:hover {
+    opacity: 1;
+}
+
+.md-tabs__link--active {
+    opacity: 1;
+}
+
+/* Admonitions */
+.md-typeset .admonition,
+.md-typeset details {
+    border-width: 0;
+    border-left-width: 4px;
+    border-radius: 4px;
+}
+
+/* Tables */
+.md-typeset table:not([class]) {
+    border-radius: 4px;
+    box-shadow: 0 2px 4px var(--md-accent-fg-color--transparent);
+}
+
+.md-typeset table:not([class]) th {
+    background-color: var(--md-accent-bg-color--light);
+    border-bottom: 2px solid var(--md-accent-fg-color--transparent);
+}
+
+/* Search */
+.md-search__form {
+    background-color: var(--md-accent-bg-color--light);
+    border-radius: 4px;
+}
+
+/* Feedback Buttons */
+.feedback-button {
+    padding: 0.5em 1em;
+    margin: 0 0.5em;
+    border-radius: 4px;
+    background-color: var(--md-accent-bg-color--light);
+    border: 1px solid var(--md-accent-fg-color--transparent);
+    color: var(--md-default-fg-color);
+    cursor: pointer;
+    transition: all 0.2s ease;
+}
+
+.feedback-button:hover {
+    background-color: var(--md-accent-fg-color--transparent);
+    border-color: var(--md-accent-fg-color);
+}
+
+.feedback-button:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+}
+
+/* Version Selector */
+.version-selector {
+    padding: 0.5em;
+    border-radius: 4px;
+    background-color: var(--md-accent-bg-color--light);
+    border: 1px solid var(--md-accent-fg-color--transparent);
+    color: var(--md-default-fg-color);
+}
+
+/* Scrollbar */
+::-webkit-scrollbar {
+    width: 8px;
+    height: 8px;
+}
+
+::-webkit-scrollbar-track {
+    background: var(--md-accent-bg-color--light);
+}
+
+::-webkit-scrollbar-thumb {
+    background: var(--md-accent-fg-color--transparent);
+    border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+    background: var(--md-accent-fg-color);
+}
+
+/* Print Styles */
+@media print {
+    .md-typeset a {
+        color: var(--md-default-fg-color) !important;
+    }
+    
+    .md-content__inner {
+        margin: 0;
+        padding: 1rem;
+    }
+} 

mkdocs.yml

@@ -1,81 +1,232 @@
-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
-  palette:
-    - scheme: default
-      primary: indigo
-      accent: indigo
-      toggle:
-        icon: material/brightness-7
-        name: Switch to dark mode
-    - scheme: slate
-      primary: indigo
-      accent: indigo
-      toggle:
-        icon: material/brightness-4
-        name: Switch to light mode
+  
+  # Modern Features
   features:
-    - navigation.instant
-    - navigation.tracking
+    # Navigation Enhancements
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.indexes
     - navigation.sections
     - navigation.expand
-    - navigation.top
+    - navigation.path
+    - navigation.footer
+    - navigation.prune
+    - navigation.tracking
+    - navigation.instant
+    
+    # UI Elements
+    - header.autohide
+    - toc.integrate
+    - toc.follow
+    - announce.dismiss
+    
+    # Search Features
     - search.suggest
     - search.highlight
+    - search.share
+    
+    # Code Features
+    - content.code.annotate
     - content.code.copy
+    - content.code.select
     - content.tabs.link
     - content.tooltips
-    - toc.integrate
+    
+  # Theme Configuration
+  palette:
+    # Dark mode as primary
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: deep-purple
+      accent: purple
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+    # Light mode as secondary
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: deep-purple
+      accent: purple
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+  
+  font:
+    text: Roboto
+    code: Roboto Mono
+  
+  icon:
+    repo: fontawesome/brands/github
+    edit: material/pencil
+    view: material/eye
 
 markdown_extensions:
+  # Modern Code Highlighting
   - pymdownx.highlight:
       anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
   - pymdownx.inlinehilite
   - pymdownx.snippets
-  - pymdownx.superfences
-  - admonition
+  
+  # Advanced Formatting
+  - pymdownx.critic
+  - pymdownx.caret
+  - pymdownx.keys
+  - pymdownx.mark
+  - pymdownx.tilde
+  
+  # Interactive Elements
   - pymdownx.details
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  
+  # Diagrams & Formatting
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.arithmatex:
+      generic: true
+  
+  # Additional Extensions
+  - admonition
   - attr_list
   - md_in_html
-  - pymdownx.emoji
-  - pymdownx.tasklist
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
   - footnotes
   - tables
+  - def_list
+  - abbr
 
 plugins:
-  - search
+  # Core Plugins
+  - search:
+      separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
   - minify:
       minify_html: true
-  - git-revision-date
-  - mkdocstrings:
-      default_handler: python
-  - social
+  - mkdocstrings
+  
+  # Advanced Features
+  - social:
+      cards: true
+      cards_color:
+        fill: "#1e1e2e"
+        text: "#cdd6f4"
   - tags
-  - redirects
-  - gh-deploy
+  - offline
+  - optimize
+  
+  # Version Management
+  - git-revision-date-localized:
+      enable_creation_date: true
+      type: date
+  
+  # Analytics
+  - analytics:
+      provider: google
+      feedback:
+        title: Was this page helpful?
+        ratings:
+          - icon: material/emoticon-happy-outline
+            name: This page was helpful
+            data: 1
+            note: >-
+              Thanks for your feedback!
+          - icon: material/emoticon-sad-outline
+            name: This page could be improved
+            data: 0
+            note: >- 
+              Thanks for your feedback!
 
+extra:
+  # Consent Management
+  consent:
+    title: Cookie consent
+    description: >- 
+      We use cookies to recognize your repeated visits and preferences, as well
+      as to measure the effectiveness of our documentation and whether users
+      find what they're searching for. With your consent, you're helping us to
+      make our documentation better.
+    actions:
+      - accept
+      - reject
+      - manage
+  
+  # Version Management
+  version:
+    provider: mike
+    default: latest
+  
+  # Social Links
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/jango-blockchained/homeassistant-mcp
+    - icon: fontawesome/brands/docker
+      link: https://hub.docker.com/r/jangoblockchained/homeassistant-mcp
+  
+  # Status Indicators
+  status:
+    new: Recently added
+    deprecated: Deprecated
+    beta: Beta
+  
+  # Analytics
+  analytics:
+    provider: google
+    property: !ENV GOOGLE_ANALYTICS_KEY
+    feedback:
+      title: Was this page helpful?
+      ratings:
+        - icon: material/emoticon-happy-outline
+          name: This page was helpful
+          data: 1
+        - icon: material/emoticon-sad-outline
+          name: This page could be improved
+          data: 0
+
+extra_css:
+  - stylesheets/extra.css
+
+extra_javascript:
+  - javascripts/mathjax.js
+  - https://polyfill.io/v3/polyfill.min.js?features=es6
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+  - javascripts/extra.js
+
+copyright: Copyright © 2025 jango-blockchained
+
+# Keep existing nav structure
 nav:
   - Home: 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
+    - Quick Start: getting-started/quickstart.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
+    - Core API: api/core.md
     - SSE API: api/sse.md
-    - Core Functions: api/core.md
+  - Usage: usage.md
+  - Configuration:
+    - System Configuration: configuration.md
   - Tools:
     - Overview: tools/tools.md
     - Device Management:
@@ -100,29 +251,12 @@ nav:
     - Best Practices: development/best-practices.md
     - Interfaces: development/interfaces.md
     - Tool Development: development/tools.md
-    - Testing Guide: testing.md
+    - Testing Guide: development/test-migration-guide.md
+    - Testing: testing.md
     - Deployment Guide: deployment.md
   - Architecture: architecture.md
   - Contributing: contributing.md
   - Troubleshooting: troubleshooting.md
   - Examples:
     - Overview: examples/index.md
-  - Roadmap: roadmap.md
-
-extra:
-  social:
-    - icon: fontawesome/brands/github
-      link: https://github.com/jango-blockchained/homeassistant-mcp
-    - icon: fontawesome/brands/docker
-      link: https://hub.docker.com/r/jangoblockchained/homeassistant-mcp
-  analytics:
-    provider: google
-    property: !ENV GOOGLE_ANALYTICS_KEY
-
-extra_css:
-  - stylesheets/extra.css
-
-extra_javascript:
-  - javascripts/extra.js
-
-copyright: Copyright © 2025 jango-blockchained
+  - Roadmap: roadmap.md