📚 Implement MkDocs with Material Theme for Documentation Build System (#78)

## 🎯 Overview

This PR implements MkDocs with the Material theme to generate HTML
documentation from the existing `docs/` folder, integrates it with
GitHub Actions, and ensures proper build artifacts management.

## 🔧 Changes Made

### Core Setup
- ✅ **MkDocs Configuration**: Created `mkdocs.yml` with Material theme
configuration
- ✅ **Documentation Structure**: Configured MkDocs to build from
`./docs/` source directory
- ✅ **Output Directory**: Set output directory to `./site/docs/`
(gitignored)
- ✅ **Dependencies**: Added `requirements.docs.txt` for MkDocs and
Material theme

### GitHub Actions Integration
- ✅ **Workflow Updates**: Modified `.github/workflows/deploy-pages.yml`
  - Added Python setup step with dependency caching
  - Added MkDocs dependency installation
  - Added MkDocs build step before deployment
- Updated workflow triggers to include `docs/**`, `mkdocs.yml`, and
`requirements.docs.txt` changes
  - Added `fetch-depth: 0` for git-revision-date-localized plugin

### Repository Management
- ✅ **Git Ignore**: Updated `.gitignore` to exclude `./site/docs/`
directory
- ✅ **Build Artifacts**: Generated documentation is treated as build
artifact (not committed)
- ✅ **Existing Structure**: Maintained existing `./site/` structure for
other static assets

## 🚀 Features Implemented

### Material Theme Configuration
- **Light/Dark Mode Toggle**: Automatic theme switching
- **Navigation**: Tabs, sections, and expandable navigation
- **Search**: Enhanced search with highlighting and sharing
- **Code Features**: Syntax highlighting with copy buttons
- **Mobile Responsive**: Optimized for mobile devices

### MkDocs Extensions
- **Admonitions**: Call-out boxes for notes, warnings, etc.
- **Code Highlighting**: Syntax highlighting with line numbers
- **Tabbed Content**: Support for tabbed sections
- **Table of Contents**: Auto-generated TOC with permalinks
- **Git Integration**: Last modified dates from Git history

### Navigation Structure
Organized documentation into logical sections:
- **Getting Started**: Installation, Quick Start, Usage
- **Configuration**: YAML Config, Template Variables, File Handling,
Mappings
- **Advanced Features**: Custom Structures, Hooks, GitHub Integration,
Schema
- **Development**: Dev Setup, Completion, Contributing
- **Reference**: Examples, Articles, Known Issues, Funding

## 🧪 Testing

- ✅ **Local Build**: `mkdocs build` successfully generates static HTML
- ✅ **Output Directory**: Documentation generated in `./site/docs/`
- ✅ **Git Ignore**: Generated files properly excluded from version
control
- ✅ **Material Theme**: Theme applied with proper styling and features
- ✅ **Navigation**: All documented pages accessible through navigation

## 📝 Usage

### Local Development
```bash
# Install dependencies
pip install -r requirements.docs.txt

# Serve documentation locally with live reload
mkdocs serve

# Build documentation
mkdocs build
```

### Production Deployment
GitHub Actions will automatically:
1. Install Python and MkDocs dependencies
2. Build documentation with `mkdocs build`
3. Deploy to GitHub Pages alongside existing static assets

## 🔗 Closes

Closes #77

## 🚦 Checklist

- [x] MkDocs installed and configured with Material theme
- [x] Documentation builds from `./docs/` source directory
- [x] Output directory set to `./site/docs/`
- [x] `mkdocs.yml` configuration file created
- [x] GitHub Actions workflow updated with MkDocs build step
- [x] Python dependencies installation added to workflow
- [x] Workflow triggers updated for documentation changes
- [x] `.gitignore` updated to exclude `./site/docs/`
- [x] Build artifacts properly managed (not committed)
- [x] Local development supports `mkdocs serve`
- [x] Documentation successfully builds and generates HTML

## 🔍 Additional Notes

- The build process shows some warnings about missing documentation
files referenced in existing docs. These can be addressed in future
updates.
- The Material theme provides excellent SEO, mobile responsiveness, and
user experience.
- The git-revision-date-localized plugin shows last modified dates for
each page.
- All existing static assets in `./site/` remain unchanged and will
continue to work.

Author: httpdss

.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

.gitignore

@@ -5,3 +5,6 @@ __pycache__
 *.log
 example_project/
 build/*
+
+# MkDocs generated documentation
+site/docs/

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

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