Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

docs(examples): Cloudflare Pages Static Deployment

Aperta
  • Qualcosa non va?
#37 0 commenti 0 reazioni 1 assegnatario Vedi su GitHub

@aRustyDev ci sta già lavorando.

Dal 5/1/2026.

Valutazione

Questa issue non è ancora stata valutata.

Descrizione

documentation

Cloudflare Pages Static Deployment

Deploy mdbook-htmx output as a static site on Cloudflare Pages.

Implementation

The Cloudflare deployment configuration lives in the mdbook-htmx repository:

mdbook-htmx/
├── wrangler.jsonc           # Wrangler configuration
├── workers/
│   ├── index.ts             # Main worker with HTMX routing
│   ├── auth.ts              # Auth utilities (Phase 3)
│   ├── search.ts            # Search handler (Phase 4)
│   ├── analytics.ts         # Analytics (Phase 5)
│   ├── package.json
│   └── tsconfig.json
├── migrations/
│   └── 0001_sessions.sql    # D1 schema (Phase 3)
└── .github/workflows/
    ├── test-deployments.yml
    └── deploy-cloudflare.yml

Production URL: https://mdbook-htmx.arusty.dev

See ADR-0016 for phase-by-phase additions.

Overview

This is the simplest deployment option—pure static files served from Cloudflare's edge network. Ideal for public documentation without authentication requirements.

Prerequisites

  • Cloudflare account
  • Wrangler CLI (npm install -g wrangler)
  • mdbook-htmx built output

Project Structure

my-docs/
├── book.toml
├── src/
│   └── ... (markdown files)
├── book/                    # mdbook-htmx output
│   ├── index.html
│   ├── manifest.json
│   ├── search-index.json
│   └── assets/
└── wrangler.toml           # Pages config

Configuration

book.toml
[book]
title = "My Documentation"
authors = ["Your Name"]
language = "en"

[output.htmx]
# Base URL for assets (Cloudflare Pages domain)
base_url = "https://docs.example.com"

# Enable asset hashing for cache busting
asset_hashing = true

# Prerender all pages for static deployment
prerender = true

# Disable server-side features
[output.htmx.search]
mode = "client"  # Client-side search only

[output.htmx.authn]
enabled = false  # No authentication
wrangler.toml
name = "my-docs"
compatibility_date = "2024-01-01"
pages_build_output_dir = "book"

# Optional: Custom headers
[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-Content-Type-Options = "nosniff"
    Referrer-Policy = "strict-origin-when-cross-origin"

# Cache static assets aggressively
[[headers]]
  for = "/assets/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

Build Script

#!/bin/bash
# build.sh

set -e

echo "Building documentation..."
mdbook build

echo "Optimizing assets..."
# Optional: Compress images, minify CSS/JS
# npx postcss book/assets/css/main.css -o book/assets/css/main.min.css

echo "Build complete!"

GitHub Actions Deployment

# .github/workflows/deploy.yml
name: Deploy to Cloudflare Pages

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      deployments: write

    steps:
      - uses: actions/checkout@v4

      - name: Install mdbook
        run: |
          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.37/mdbook-v0.4.37-x86_64-unknown-linux-gnu.tar.gz | tar -xz
          chmod +x mdbook
          sudo mv mdbook /usr/local/bin/

      - name: Install mdbook-htmx
        run: |
          cargo install mdbook-htmx

      - name: Build documentation
        run: mdbook build

      - name: Deploy to Cloudflare Pages
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: my-docs
          directory: book
          gitHubToken: ${{ secrets.GITHUB_TOKEN }}
          branch: ${{ github.head_ref || github.ref_name }}

Custom Domain Setup

  1. In Cloudflare Dashboard → Pages → your-project → Custom domains
  2. Add domain: docs.example.com
  3. DNS will be configured automatically if domain is on Cloudflare

Redirects

Create book/_redirects for URL handling:

# Redirect old paths
/old-page   /new-page   301

# SPA fallback (if needed)
/*          /index.html   200

Headers

Create book/_headers for custom response headers:

# All pages
/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'

# Cache static assets
/assets/*
  Cache-Control: public, max-age=31536000, immutable

# Don't cache HTML
/*.html
  Cache-Control: public, max-age=0, must-revalidate

Performance Optimization

Enable Brotli Compression

Cloudflare automatically compresses responses. Ensure it's enabled:

  1. Dashboard → your-domain → Speed → Optimization
  2. Enable "Brotli"
Image Optimization

Use Cloudflare Image Resizing for dynamic image optimization:

<img src="/cdn-cgi/image/width=800,quality=80/images/diagram.png" alt="Diagram">

Monitoring

Web Analytics

Enable Cloudflare Web Analytics (privacy-friendly):

<!-- In layout.html before </body> -->
<script defer src='https://static.cloudflareinsights.com/beacon.min.js'
        data-cf-beacon='{"token": "your-token"}'></script>
Page Views in Dashboard

View analytics at: Dashboard → Pages → your-project → Analytics

Cost

  • Free tier: Unlimited requests, 500 builds/month
  • Pro: $20/month for advanced features

Limitations

  • No server-side rendering
  • No authentication (use cf-workers-d1 for auth)
  • No server-side search (client-side only)
  • Build output limited to 25,000 files, 25 MB per file

Next Steps

Lingua principale
Rust
Stelle
0
Fork
1
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di aRustyDev/mdbook-htmx

Tutte le issue di aRustyDev/mdbook-htmx

Issue simili

Altre issue su Rust

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.