From 41504db49e9e21b5f6f2ead9a0e08aa234192102 Mon Sep 17 00:00:00 2001
From: Kenneth Belitzky <kenny@belitzky.com>
Date: Sat, 2 Aug 2025 09:21:23 -0300
Subject: [PATCH] feat: implement MkDocs with Material theme for documentation
 build system
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add mkdocs.yml configuration with Material theme
- Create requirements.docs.txt for MkDocs dependencies
- Update .gitignore to exclude generated site/docs/ directory
- Modify GitHub Actions workflow to build and deploy MkDocs documentation
- Add Python setup and MkDocs build steps to deploy-pages workflow
- Update workflow triggers to include docs/** path changes

Implements issue #77:
- ✅ Core Setup: MkDocs with Material theme configured
- ✅ GitHub Actions Integration: Workflow updated with build steps
- ✅ Repository Management: Generated docs excluded from version control
- ✅ Local Development: Supports 'mkdocs serve' for live preview
- ✅ Build Process: 'mkdocs build' generates static HTML in ./site/docs/

Co-authored-by: AI Assistant
---
 .github/workflows/deploy-pages.yml | 19 +++++++
 .gitignore                         |  3 ++
 mkdocs.yml                         | 83 ++++++++++++++++++++++++++++++
 requirements.docs.txt              |  3 ++
 4 files changed, 108 insertions(+)
 create mode 100644 mkdocs.yml
 create mode 100644 requirements.docs.txt

diff --git a/.github/workflows/deploy-pages.yml b/.github/workflows/deploy-pages.yml
index e0adb44..c02ee72 100644
--- a/.github/workflows/deploy-pages.yml
+++ b/.github/workflows/deploy-pages.yml
@@ -5,6 +5,9 @@ on:
     branches: ["main"]
     paths:
       - "site/**"
+      - "docs/**"
+      - "mkdocs.yml"
+      - "requirements.docs.txt"
 
   workflow_dispatch:
 
@@ -26,6 +29,22 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Needed for git-revision-date-localized plugin
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.x'
+          cache: 'pip'
+
+      - name: Install MkDocs dependencies
+        run: |
+          pip install -r requirements.docs.txt
+
+      - name: Build MkDocs documentation
+        run: |
+          mkdocs build
 
       - name: Setup Pages
         uses: actions/configure-pages@v5
diff --git a/.gitignore b/.gitignore
index e2828c3..ff9930a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,3 +5,6 @@ __pycache__
 *.log
 example_project/
 build/*
+
+# MkDocs generated documentation
+site/docs/
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..f57e690
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,83 @@
+site_name: STRUCT Documentation
+site_description: Automated Project Structure Generator
+site_url: https://httpdss.github.io/struct/
+repo_url: https://github.com/httpdss/struct
+repo_name: httpdss/struct
+
+theme:
+  name: material
+  palette:
+    # Palette toggle for light mode
+    - scheme: default
+      primary: blue
+      accent: blue
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - scheme: slate
+      primary: blue
+      accent: blue
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.expand
+    - navigation.top
+    - search.highlight
+    - search.share
+    - content.code.copy
+    - content.code.annotate
+
+docs_dir: docs
+site_dir: site/docs
+
+# Navigation structure based on existing docs
+nav:
+  - Home: index.md
+  - Getting Started:
+    - Installation: installation.md
+    - Quick Start: quickstart.md
+    - Usage: usage.md
+  - Configuration:
+    - YAML Configuration: configuration.md
+    - Template Variables: template-variables.md
+    - File Handling: file-handling.md
+    - Mappings: mappings.md
+  - Advanced Features:
+    - Custom Structures: structures.md
+    - Hooks: hooks.md
+    - GitHub Integration: github-integration.md
+    - Schema Reference: schema.md
+  - Development:
+    - Development Setup: development.md
+    - Command-Line Completion: completion.md
+    - Contributing: contributing.md
+  - Reference:
+    - Examples: examples/index.md
+    - Articles and Tutorials: articles.md
+    - Known Issues: known-issues.md
+    - Funding: funding.md
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.tabbed:
+      alternate_style: true
+  - attr_list
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+
+plugins:
+  - search
+  - git-revision-date-localized:
+      enable_creation_date: true
diff --git a/requirements.docs.txt b/requirements.docs.txt
new file mode 100644
index 0000000..58b7ec6
--- /dev/null
+++ b/requirements.docs.txt
@@ -0,0 +1,3 @@
+mkdocs>=1.5.0
+mkdocs-material>=9.0.0
+mkdocs-git-revision-date-localized-plugin>=1.2.0