📚 Implement MkDocs with Material Theme for Documentation Build System #77

🎯 Overview

Implement MkDocs with the Material theme to generate HTML documentation from our existing docs/ folder, integrate it with GitHub Actions, and ensure proper build artifacts management.

📋 Requirements

Core Setup

• Install and configure MkDocs with mkdocs-material theme
• Configure MkDocs to build from ./docs/ source directory
• Set output directory to ./site/docs/ (currently non-existent)
• Create mkdocs.yml configuration file in project root

GitHub Actions Integration

• Modify .github/workflows/deploy-pages.yml to:
  • Add MkDocs build step before deployment
  • Install Python dependencies (MkDocs + Material theme)
  • Run mkdocs build command to generate static HTML
  • Update workflow triggers to include docs/** path changes
  • Ensure built documentation is deployed to GitHub Pages

Repository Management

• Update .gitignore to exclude ./site/docs/ directory
• Ensure ./site/docs/ is treated as build artifact (not committed)
• Maintain existing ./site/ structure for other static assets

🔧 Technical Considerations

MkDocs Configuration (mkdocs.yml)

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
  # Additional Material theme configuration

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
  # ... additional navigation structure

GitHub Actions Workflow Updates

• Add Python setup step
• Install MkDocs and Material theme via pip
• Run mkdocs build to generate ./site/docs/
• Ensure the existing deployment process remains intact
• Consider caching Python dependencies for faster builds

Directory Structure After Implementation

.
├── docs/              # Source documentation (existing)
├── site/
│   ├── docs/          # Generated MkDocs HTML (new, gitignored)
│   ├── css/           # Existing static assets
│   ├── js/            # Existing static assets
│   ├── index.html     # Existing homepage
│   └── ...            # Other existing assets
└── mkdocs.yml         # MkDocs configuration (new)

🚀 Expected Outcomes

1. Local Development: Developers can run mkdocs serve for live documentation preview
2. Build Process: mkdocs build generates static HTML in ./site/docs/
3. CI/CD Integration: GitHub Actions automatically builds and deploys documentation
4. SEO & UX: Material theme provides better navigation, search, and mobile experience
5. Maintenance: Documentation updates trigger automatic rebuilds and deployments

🔗 Dependencies

• mkdocs (latest stable)
• mkdocs-material theme
• Python 3.x in GitHub Actions environment
• Existing GitHub Pages setup (already configured)

🏷️ Labels

documentation, enhancement, mkdocs, github-actions, build-system

💡 Additional Considerations

• Theme Customization: Material theme supports extensive customization for branding
• Search Integration: Built-in search functionality with Material theme
• Mobile Responsiveness: Improved mobile documentation experience
• Plugin Ecosystem: MkDocs supports various plugins for enhanced functionality
• Version Control: Only source files in docs/ are version controlled, not generated HTML
• Performance: Static HTML generation provides fast page loads

Acceptance Criteria: Documentation can be built locally with mkdocs build, GitHub Actions successfully generates and deploys the documentation, and ./site/docs/ is properly excluded from version control.