Skip to main content

MkDocs Deployment to Cloudflare Pages

This project uses MkDocs with the Material for MkDocs theme to generate documentation that can be deployed to Cloudflare Pages.

Local Development​

Prerequisites​

  • Python 3.11+
  • pip

Setup​

# Install dependencies
pip install -r requirements.txt

# Serve locally
mkdocs serve

The documentation will be available at http://localhost:8000

Build​

# Build static site
mkdocs build

# Output will be in site/ directory

Cloudflare Pages Deployment​

  1. Connect Repository to Cloudflare Pages

    • Go to Cloudflare Pages dashboard
    • Click "Create a project"
    • Connect your GitHub repository
    • Select the axelites/logidav repository

  2. Configure Build Settings

    • Framework preset: None (or Other)
    • Build command: mkdocs build
    • Build output directory: site
    • Root directory: / (leave empty or root)
    • Environment variables:
      • PYTHON_VERSION: 3.11

  3. Deploy

    • Click "Save and Deploy"
    • Cloudflare will automatically build and deploy on every push to the main branch

Build Configuration​

The build uses:

  • Python 3.11 (specified in .python-version)
  • MkDocs with Material theme
  • Dependencies from requirements.txt

Build command installs dependencies automatically:

pip install -r requirements.txt
mkdocs build

Preview Deployments​

Cloudflare Pages creates preview deployments for:

  • Pull requests
  • Non-production branches

Each preview gets a unique URL for testing before merging.

Documentation Structure​

docs/
├── index.md                    # Home page
├── README.md                   # System overview
├── system-crontab.md          # Source crontab
├── cronjobs/
│   ├── index.md               # Cronjobs overview
│   ├── critical/              # Critical risk commands
│   ├── high/                  # High risk commands
│   ├── all/                   # Alphabetical listing
│   └── [115 cronjob docs]     # Individual command docs
├── meta/
│   └── documentation-progress.md
├── stylesheets/
│   └── extra.css              # Custom styles
└── [other docs]

Configuration​

mkdocs.yml​

Main configuration file defining:

  • Site metadata
  • Theme (Material for MkDocs)
  • Navigation structure
  • Plugins and extensions
  • Custom styling

Key Features​

  • Material Design theme with light/dark mode
  • Search functionality
  • Code syntax highlighting with copy button
  • Mermaid diagrams support
  • Responsive design
  • Navigation tabs for main sections
  • Table of contents tracking

Updating Documentation​

Regenerate Cronjob Docs​

# After crontab changes
python3 tools/cronjob_doc_generator.py

# Test locally
mkdocs serve

# Commit and push
git add docs/ mkdocs.yml
git commit -m "docs: update cronjobs"
git push

Cloudflare will automatically rebuild and redeploy.

Custom Pages​

  1. Create/edit markdown files in docs/
  2. Update navigation in mkdocs.yml if needed
  3. Test locally with mkdocs serve
  4. Commit and push

Troubleshooting​

Build Fails on Cloudflare​

  1. Check build logs in Cloudflare Pages dashboard
  2. Verify requirements.txt is present
  3. Ensure PYTHON_VERSION environment variable is set
  4. Test build locally: mkdocs build

Missing Dependencies​

# Install/update dependencies
pip install -r requirements.txt --upgrade
  • Check mkdocs.yml nav section
  • Ensure all referenced files exist
  • Verify file paths are relative to docs/

Resources​

Site URL​

Once deployed, the documentation will be available at:

  • Production: https://docs-logidav.pages.dev (or custom domain)
  • Preview: https://[hash].docs-logidav.pages.dev