Installation Guide¶

Complete installation instructions for Material for MkDocs documentation site for Digital Memory Chest.

Prerequisites¶

System Requirements¶

Quick Installation¶

1. Install MkDocs Material¶

# Install MkDocs Material and plugins
pip install mkdocs-material

# Install required plugins
pip install mkdocs-mermaid2-plugin
pip install mkdocs-glightbox

2. Clone Documentation¶

# Clone the Digital Memory Chest repository
git clone https://github.com/your-username/digital-memory-chest
cd digital-memory-chest

# Verify documentation structure
ls docs/

3. Build and Serve¶

# Serve documentation locally
mkdocs serve

# Or build static files
mkdocs build

Visit http://localhost:8000 to view your documentation!

Detailed Installation¶

Python Environment Setup¶

# Create virtual environment
python -m venv venv-docs
source venv-docs/bin/activate  # On Windows: venv-docs\Scripts\activate

# Upgrade pip
pip install --upgrade pip

# Install full documentation stack
pip install -r docs-requirements.txt

Create docs-requirements.txt:

mkdocs-material>=9.4.0
mkdocs-mermaid2-plugin>=1.1.0
mkdocs-glightbox>=0.3.0
pymdown-extensions>=10.0

Plugin Configuration¶

The documentation uses several plugins for enhanced functionality:

plugins:
  - mermaid2:
      arguments:
        theme: |
          ^(auto|dark|light)$

plugins:
  - glightbox:
      touchNavigation: true
      loop: false
      effect: zoom
      slide_effect: slide
      width: 100%
      height: auto
      zoomable: true
      draggable: true

plugins:
  - search:
      lang: en
      separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'

Theme Customization¶

Color Scheme¶

The documentation uses a memorial-appropriate color palette:

# mkdocs.yml
theme:
  name: material
  palette:
    # Light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: deep purple
      accent: purple
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

    # Dark mode  
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: deep purple
      accent: purple
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

Custom Styling¶

The docs/stylesheets/extra.css file includes:

• Memorial Theme: Respectful purple color scheme
• Enhanced Cards: Beautiful grid layouts with gradients
• Interactive Elements: Hover effects and animations
• Responsive Design: Mobile-first approach
• Dark Mode Support: Automatic theme switching
• Accessibility: High contrast and reduced motion support

Logo and Branding¶

theme:
  icon:
    repo: fontawesome/brands/github
    logo: material/heart-box  # Memorial-appropriate icon

  favicon: images/favicon.ico

Advanced Configuration¶

Site Analytics¶

extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX  # Replace with your Google Analytics ID

  # Alternative: Use privacy-friendly analytics
  # analytics:
  #   provider: plausible
  #   property: your-domain.com

Social Links¶

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/your-username/digital-memory-chest
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/your-handle
    - icon: fontawesome/solid/envelope
      link: mailto:contact@your-domain.com

Versioning Support¶

extra:
  version:
    provider: mike
    default: stable

Enable version management:

# Install mike for version management
pip install mike

# Deploy versioned docs
mike deploy --push --update-aliases 1.0 latest
mike deploy --push --update-aliases 2.0 stable

Production Deployment¶

Static Site Hosting¶

GitHub Pages¶

# .github/workflows/docs.yml
name: Deploy Documentation

on:
  push:
    branches: [ main ]
    paths: [ 'docs/**', 'mkdocs.yml' ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0

    - name: Setup Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.11'

    - name: Install dependencies
      run: |
        pip install -r docs-requirements.txt

    - name: Build and deploy
      run: |
        mkdocs gh-deploy --force

Netlify¶

# netlify.toml
[build]
  command = "pip install -r docs-requirements.txt && mkdocs build"
  publish = "site"

[build.environment]
  PYTHON_VERSION = "3.11"

Vercel¶

{
  "builds": [
    {
      "src": "mkdocs.yml",
      "use": "@vercel/static-build",
      "config": {
        "distDir": "site"
      }
    }
  ],
  "buildCommand": "pip install -r docs-requirements.txt && mkdocs build"
}

Self-Hosted Setup¶

Nginx Configuration¶

server {
    listen 80;
    listen [::]:80;
    server_name docs.your-domain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name docs.your-domain.com;

    # SSL Configuration
    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;

    # Document root
    root /var/www/digital-memory-chest-docs/site;
    index index.html;

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "no-referrer-when-downgrade" always;
    add_header Content-Security-Policy "default-src 'self' http: https: data: blob: 'unsafe-inline'" always;

    # Gzip compression
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_proxied expired no-cache no-store private must-revalidate auth;
    gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/xml+rss;

    # Cache static assets
    location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # Main site
    location / {
        try_files $uri $uri/ =404;
    }
}

Docker Deployment¶

# Dockerfile.docs
FROM python:3.11-alpine

WORKDIR /docs

# Install dependencies
COPY docs-requirements.txt .
RUN pip install --no-cache-dir -r docs-requirements.txt

# Copy documentation
COPY docs/ docs/
COPY mkdocs.yml .

# Build static site
RUN mkdocs build

# Serve with lightweight HTTP server
FROM nginx:alpine
COPY --from=0 /docs/site /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf

EXPOSE 80

# Build and run
docker build -f Dockerfile.docs -t dmc-docs .
docker run -p 8080:80 dmc-docs

Customization Guide¶

Adding New Pages¶

1. Create Markdown File:

   touch docs/new-section/new-page.md
   

2. Update Navigation:

   nav:
     - New Section:
       - New Page: new-section/new-page.md
   

3. Follow Content Guidelines:

4. Use consistent heading structure
5. Include diagrams where helpful
6. Add cross-references to related pages
7. Follow the established tone and style

Custom Components¶

Info Cards¶

<div class="grid cards" markdown>

-   :material-heart:{ .lg .middle } **Feature Title**

    ---

    Feature description with compelling content

    [:octicons-arrow-right-24: Learn More](link.md)

</div>

Status Indicators¶

<span class="status-indicator complete">✅ Complete</span>
<span class="status-indicator processing">🔄 Processing</span>
<span class="status-indicator pending">⏳ Pending</span>
<span class="status-indicator failed">❌ Failed</span>

Timeline Items¶

<div class="timeline-item">
  <h4>Step Title</h4>
  <p>Step description with detailed information.</p>
</div>

Diagram Creation¶

Mermaid Best Practices¶

%%{init: {'theme':'base', 'themeVariables': {'primaryColor': '#673ab7', 'primaryTextColor': '#fff', 'primaryBorderColor': '#512da8', 'lineColor': '#9c27b0'}}}%%
graph TB
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]

    style A fill:#e3f2fd
    style C fill:#e8f5e8
    style D fill:#fff3e0

Tips: - Use consistent color schemes - Keep diagrams focused and readable - Include both thumbnail and full-resolution versions - Test across light and dark themes

Troubleshooting¶

Common Issues¶

# Check Python version
python --version  # Should be 3.8+

# Clear cache and rebuild
mkdocs build --clean

# Check for plugin conflicts
mkdocs serve --verbose

# Update all plugins
pip install --upgrade mkdocs-material mkdocs-mermaid2-plugin mkdocs-glightbox

# Check plugin versions
pip list | grep mkdocs

# Reset to default theme temporarily
mkdocs serve --theme material

# Check custom CSS syntax
# Validate mkdocs.yml configuration

Performance Optimization¶

• Image Optimization: Compress images before adding to docs
• Mermaid Caching: Enable diagram caching for faster builds
• Lazy Loading: Use for large image galleries
• CDN: Consider using CDN for static assets in production