MkDocs

MkDocs is a Python-based static site generator designed for project documentation. It outputs a fully static site to site/ by default. pageflare integrates as a post-build step — chain it after mkdocs build.

Works with both the default theme and Material for MkDocs.

Install

# Shell (Linux/macOS)
curl -fsSL https://get.appz.dev/pageflare/install.sh | sh

# Homebrew
brew tap getappz/tap && brew install pageflare

# npm (if you have Node.js available)
npm install -g @pageflare/cli

Usage

Run pageflare after MkDocs builds:

mkdocs build && pageflare site/ --in-place

Configuration

Create a pageflare.jsonc in your project root:

{
  "minify_html": true,
  "minify_css": true,
  "minify_js": true,
  "js_defer": true,
  "lazy_images": true,
  "img_dimensions": true,
  "font_swap": true,
  "preconnect_hints": true
}

If you use a custom output dir (mkdocs build -d build/), pass the same path:

mkdocs build -d build && pageflare build/ --in-place

What pageflare Adds

MkDocs (and Material for MkDocs) handles theming and navigation but does not optimize the final output. pageflare adds:

HTML, CSS, and JS minification
Lazy loading and image dimension inference
JavaScript defer and loader injection
Font display swap and self-hosting
Preconnect hints for third-party origins
Critical CSS extraction (Pro)
Responsive image srcset generation (Pro)

Material for MkDocs

Material for MkDocs has a built-in minify plugin. You can use both — Material handles HTML minification, pageflare handles everything else:

{
  "minify_html": false,
  "minify_css": true,
  "minify_js": true
}

Or let pageflare handle all minification and skip the Material plugin.

CI/CD Integration

GitHub Actions

- name: Setup Python
  uses: actions/setup-python@v5
  with:
    python-version: '3.12'

- name: Install MkDocs
  run: pip install mkdocs mkdocs-material

- name: Build docs
  run: mkdocs build

- name: Optimize with pageflare
  uses: getappz/pageflare-cli@v1
  with:
    args: "site/ --in-place"

Netlify

[build]
  command = "mkdocs build && pageflare site/ --in-place --no-progress"
  publish = "site"

Vercel

{
  "buildCommand": "pip install mkdocs && mkdocs build && pageflare site/ --in-place --no-progress"
}

Read the Docs

Read the Docs uses its own build pipeline and does not support post-build hooks. To use pageflare, switch to a self-hosted deployment with GitHub Actions or Netlify.

Replacing plugins

MkDocs has Python-based plugins for optimization. After adding pageflare, you can remove:

Plugin	pageflare equivalent
`mkdocs-minify-plugin`	HTML minification
`mkdocs-redirects`	Keep — pageflare doesn’t handle redirects

Pro License

Set the PAGEFLARE_LICENSE environment variable to unlock Pro optimizations:

PAGEFLARE_LICENSE=your-key mkdocs build && pageflare site/ --in-place

Deploying

MkDocs static output works with any hosting provider:

Vercel — automatic Vercel Image Optimization
Netlify — automatic Netlify Image CDN
Cloudflare Pages — Cloudflare Image Resizing
Self-hosted — any static file server

Troubleshooting

pageflare processes 0 files Verify the output directory — MkDocs defaults to site/ but this can be changed via site_dir in mkdocs.yml.

Search broken after optimization MkDocs search relies on search_index.json. pageflare does not modify JSON files, so search should work normally. If search breaks, check that JS deferral isn’t delaying the search script — disable it if needed:

{ "js_defer": false }

Font loading issues with Material theme Material for MkDocs loads Google Fonts by default. pageflare’s font self-hosting feature will download and serve them locally, which is usually faster. If you see font rendering issues, check that self_host_google_fonts is working correctly by inspecting the generated CSS.