Skip to content

MKDOCS IMPLEMENTATION

Kaizen-OS MkDocs Branding Implementation Summary

Date: C-126 (November 6, 2025)
Status: ✅ Complete

Overview

Complete MkDocs Material theme implementation with Kaizen-OS branding, including custom color system, logo, and GitHub Pages deployment.

Files Created

Configuration

  • ✅ mkdocs.yml - Complete MkDocs configuration with Kaizen navigation structure
  • ✅ docs/requirements.txt - Python dependencies for MkDocs

Branding Assets

  • ✅ docs/assets/logo/kaizen-logo.svg - Main Kaizen logo (Kintsugi-inspired design)
  • ✅ docs/assets/logo/kaizen-favicon.svg - Favicon version
  • ✅ docs/assets/css/kaizen-theme.css - Custom CSS theme with Kaizen colors
  • ✅ docs/assets/js/kaizen-enhancements.js - Interactive enhancements
  • ✅ docs/assets/README.md - Branding assets documentation

Documentation

  • ✅ docs/index.md - Homepage for MkDocs site
  • ✅ docs/MKDOCS_GUIDE.md - Setup and usage guide

CI/CD

  • ✅ .github/workflows/mkdocs-pages.yml - GitHub Actions workflow for auto-deployment

Color System

Based on Kaizen Visual Design System v1.0.0:

Primary Colors

  • Deep Teal #2C4F5E - Primary background (contemplation, depth)
  • Darker Teal #1A2F3A - Depth, shadows
  • Lighter Teal #3D5A6B - Highlights, clarity

Accent Colors

  • Gold #FFD700 - Healing, accent, emphasis (Kintsugi seams)
  • Gold Dark #B8860B - Hover states

Text Colors

  • Cream #F5E6D3 - Primary text (illumination)
  • Warm Beige #D4C5A9 - Secondary text (ceramic)

Logo Design

The Kaizen logo features: - Deep Teal circular background representing contemplation - Warm Beige vessel shape representing the system - Gold Kintsugi repair seams representing healing and integrity - Central and outer nodes representing connected systems - Inspired by Japanese Kintsugi (金継ぎ) philosophy

Features Implemented

Theme Features

  • ✅ Dark mode (default) with Deep Teal theme
  • ✅ Light mode toggle
  • ✅ Custom Kaizen color palette
  • ✅ Kintsugi-inspired styling
  • ✅ Responsive design
  • ✅ Complete site navigation structure
  • ✅ Tabbed navigation
  • ✅ Sticky navigation
  • ✅ Section indexes
  • ✅ Breadcrumbs

Content Features

  • ✅ Code syntax highlighting
  • ✅ Copy-to-clipboard for code blocks
  • ✅ Admonitions (notes, tips, warnings)
  • ✅ Tables with Kaizen styling
  • ✅ Search functionality
  • ✅ Git revision dates

Interactive Enhancements

  • ✅ Kaizen motto in footer
  • ✅ Smooth scrolling
  • ✅ Keyboard shortcuts (/ for search)
  • ✅ GI badge display (if available)
  • ✅ Cycle badge display (if available)

GitHub Pages Deployment

The site automatically deploys when: - Changes are pushed to main branch - Files in docs/ are modified - mkdocs.yml is updated

Deployment URL: https://kaizencycle.github.io/Kaizen-OS/

Usage

Local Development

pip install -r docs/requirements.txt
mkdocs serve

Production Build

mkdocs build --strict

Manual Deployment

mkdocs gh-deploy

Next Steps

  1. Enable GitHub Pages:
  2. Go to repository Settings → Pages
  3. Source: "GitHub Actions"

  4. Save

  5. Test Locally: 

    cd docs
pip install -r requirements.txt
mkdocs serve

  6. Verify Navigation:

  7. Check that all links in mkdocs.yml point to existing files

  8. Update navigation as needed

  9. Customize:

  10. Adjust colors in docs/assets/css/kaizen-theme.css
  11. Modify logo if needed
  12. Update navigation structure in mkdocs.yml

Design Philosophy

The theme embodies Kaizen principles:

  • Kintsugi: Golden repair seams visible in logo and accent colors
  • Contemplation: Deep Teal backgrounds create contemplative atmosphere
  • Healing: Gold accents represent the healing process
  • Integrity: Clean, structured design reflects system integrity

References

"We heal as we walk." — Kaizen Cycle