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

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/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,12 +1,45 @@
-mkdocs>=1.5.0
-mkdocs-material>=9.0.0
+# Core
+mkdocs>=1.5.3
+mkdocs-material>=9.5.3
+
+# Enhanced Functionality
 mkdocs-minify-plugin>=0.7.1
-mkdocstrings>=0.24.0
-mkdocstrings-python>=1.0.0
-mkdocs-social-plugin==0.1.0
-mkdocs-redirects>=1.2.1
+mkdocs-git-revision-date-localized-plugin>=1.2.1
 mkdocs-glightbox>=0.3.4
-pillow>=10.0.0
-cairosvg>=2.7.0
-pymdown-extensions>=10.0
-mkdocs-git-revision-date-plugin 
+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;
+    }
+}