Documentation Deployment

This guide covers how the Meister Bill documentation is built and deployed.

Overview

The documentation is built using MkDocs with the ReadTheDocs theme, and deployed to Cloudflare Pages.

Architecture

┌─────────────────┐     ┌──────────────┐     ┌──────────────────┐
│   docs/         │────▶│  MkDocs      │────▶│  Cloudflare      │
│   (Markdown)    │     │  (Build)     │     │  Pages           │
└─────────────────┘     └──────────────┘     └──────────────────┘
                              │                       │
                              ▼                       ▼
                        ┌──────────┐          ┌──────────────┐
                        │  site/   │          │ docs.meister-│
                        │ (HTML)   │          │ bill.com     │
                        └──────────┘          └──────────────┘

Local Development

Prerequisites

  • Python 3.8+
  • pip

Setup

# Create virtual environment
python3 -m venv /tmp/mkdocs-venv
source /tmp/mkdocs-venv/bin/activate

# Install dependencies
pip install mkdocs mkdocs-material

Development Server

# Start development server
mkdocs serve

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

Building

# Build for production
source /tmp/mkdocs-venv/bin/activate
mkdocs build --strict

# Output will be in site/ directory

Deployment

Automatic Deployment (CI/CD)

Documentation is automatically deployed when: - Changes are pushed to main branch - Files in docs/ directory are modified - mkdocs.yml is modified - The workflow file .gitea/workflows/deploy-docs.yml is modified

Manual Deployment

# Ensure you're logged into Cloudflare
pnpm exec wrangler login

# Build and deploy
source /tmp/mkdocs-venv/bin/activate
mkdocs build --strict
./node_modules/.pnpm/node_modules/.bin/wrangler pages deploy site \
    --project-name=meisterbill-docs \
    --branch=main

Configuration Files

File Purpose
mkdocs.yml MkDocs configuration (theme, navigation, extensions)
wrangler-docs.toml Cloudflare Pages deployment configuration
docs/_headers Security headers for all pages
docs/_redirects URL redirect rules
.gitea/workflows/deploy-docs.yml CI/CD workflow

Security Headers

The following security headers are applied to all documentation pages:

  • X-Frame-Options: DENY - Prevents clickjacking
  • X-Content-Type-Options: nosniff - Prevents MIME sniffing
  • X-XSS-Protection: 1; mode=block - XSS protection
  • Referrer-Policy: strict-origin-when-cross-origin - Referrer policy
  • Content-Security-Policy - Restricts resource loading

Troubleshooting

Build Failures

# Check for broken links
mkdocs build --strict

# Verbose output
mkdocs build --verbose

Deployment Failures

Check the CI/CD logs in Gitea: 1. Go to Actions tab 2. Select Deploy Documentation workflow 3. Check the deployment step logs

URLs

Environment URL
Production https://docs.meister-bill.com
Cloudflare Pages https://meisterbill-docs.pages.dev

  • 278 - Migrate MkDocs documentation to Cloudflare