Skip to content

Deploying to Cloudflare Pages

This guide explains how to deploy your MkDocs documentation to Cloudflare Pages.

What is Cloudflare Pages?

Cloudflare Pages is a JAMstack platform for deploying static sites. It offers:

  • Automatic builds from your Git repository
  • Global CDN for fast content delivery
  • Free SSL certificates
  • Unlimited bandwidth and requests
  • Preview deployments for pull requests
  • Custom domains support

Prerequisites

Before deploying, you need:

  1. A Cloudflare account (free tier is sufficient)
  2. Your MkDocs project in a Git repository (GitHub, GitLab, or Bitbucket)
  3. The project configured with mkdocs.yml

Deployment Steps

Step 1: Connect Your Repository

  1. Log in to the Cloudflare Dashboard
  2. Navigate to Pages in the sidebar
  3. Click Create a project
  4. Select Connect to Git
  5. Authorize Cloudflare to access your Git provider
  6. Select your repository

Step 2: Configure Build Settings

Configure the build settings for your MkDocs project:

Build configuration:

  • Framework preset: None (or Custom)
  • Build command: mkdocs build
  • Build output directory: site
  • Root directory: / (or your project directory)

Environment variables:

You may need to set:

PYTHON_VERSION=3.11

Step 3: Deploy

  1. Click Save and Deploy
  2. Cloudflare Pages will clone your repository and run the build
  3. Wait for the build to complete (usually 1-3 minutes)
  4. Your site will be available at https://<project-name>.pages.dev

Build Command Details

The build process runs:

# Install dependencies
pip install -r requirements.txt

# Build the site
mkdocs build

Make sure your requirements.txt includes:

mkdocs>=1.5.0
mkdocs-material>=9.0.0

Continuous Deployment

Once configured, Cloudflare Pages automatically:

  • Rebuilds your site when you push to your default branch
  • Creates preview deployments for pull requests
  • Deploys changes globally within seconds

Custom Domains

To use a custom domain:

  1. Go to your project in Cloudflare Pages
  2. Navigate to Custom domains
  3. Click Set up a custom domain
  4. Follow the instructions to configure DNS
  5. Wait for SSL certificate provisioning (automatic)

Troubleshooting

Build Failures

If your build fails:

  1. Check the build logs in Cloudflare Pages dashboard
  2. Verify requirements.txt contains all dependencies
  3. Ensure Python version is compatible (3.8+)
  4. Test the build locally: mkdocs build

Common Issues

Issue: Module not found errors

Solution: Add missing dependencies to requirements.txt

Issue: Build timeout

Solution: Optimize your documentation or contact Cloudflare support

Issue: 404 errors after deployment

Solution: Check that site is set as the build output directory

Deployment Workflows

Production Workflow

graph LR
    A[Push to main] --> B[Cloudflare triggers build]
    B --> C[Install dependencies]
    C --> D[Run mkdocs build]
    D --> E[Deploy to production]
    E --> F[Available globally]

Preview Workflow

graph LR
    A[Open PR] --> B[Cloudflare creates preview]
    B --> C[Build preview site]
    C --> D[Preview URL available]
    D --> E[Review changes]

Best Practices

  1. Test locally before pushing
  2. Use version pinning in requirements.txt
  3. Keep dependencies minimal for faster builds
  4. Monitor build times and optimize if needed
  5. Use preview deployments to test changes

Next Steps

Learn about configuration options for advanced customization.