Jekyll

Jekyll is a Ruby-based static site generator and the default engine behind GitHub Pages. It outputs a fully static site to _site/ by default. pageflare integrates as a post-build step — chain it after jekyll build.

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 in your project)
npm install -D @pageflare/cli

Usage

Run pageflare after Jekyll builds:

jekyll build && pageflare _site/ --in-place

If you have a package.json in your project:

package.json

{
  "scripts": {
    "build": "jekyll build && pageflare _site/ --in-place"
  }
}

Configuration

Create a pageflare.jsonc in your project root:

pageflare.jsonc

{
  "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 (jekyll build -d build/), pass the same path:

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

What pageflare Adds

Jekyll does not minify or optimize its 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)

GitHub Pages

Jekyll is the default build tool for GitHub Pages. There are two approaches:

Option 1: GitHub Actions (recommended)

Use a custom workflow instead of the default GitHub Pages build:

.github/workflows/pages.yml

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

permissions:
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.3'
          bundler-cache: true

      - name: Build Jekyll
        run: bundle exec jekyll build

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

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: _site/

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
    steps:
      - uses: actions/deploy-pages@v4

Option 2: Build locally

Build and optimize locally, then push the output:

jekyll build && pageflare _site/ --in-place
# Push _site/ to your gh-pages branch or deploy target

Other CI/CD Platforms

Netlify

netlify.toml

[build]
  command = "jekyll build && pageflare _site/ --in-place --no-progress"
  publish = "_site"

Vercel

vercel.json

{
  "buildCommand": "jekyll build && pageflare _site/ --in-place --no-progress"
}

Replacing plugins

Jekyll has gems for optimization. After adding pageflare, you can remove:

Gem / Tool	pageflare equivalent
jekyll-minifier	HTML, CSS, JS minification
jekyll-sitemap	Sitemap generation via llm.sitemap config
jekyll-seo-tag	Keep — pageflare handles performance, not meta tags
jekyll-responsive-image	Image optimization, responsive srcset, lazy loading

Tip

Every gem you remove is one less Ruby dependency. pageflare is a standalone binary — it doesn’t need Ruby, Node, or any runtime.

Pro License

Set the PAGEFLARE_LICENSE environment variable to unlock Pro optimizations:

PAGEFLARE_LICENSE=your-key jekyll build && pageflare _site/ --in-place

Deploying

Jekyll 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 Jekyll finished building — check that _site/ contains HTML files. The output directory can be changed via destination in _config.yml.

Sass files not optimized Jekyll compiles Sass to CSS during build. pageflare processes the compiled CSS in _site/, not the source .scss files. Both work together without conflict.

GitHub Pages default build ignores pageflare The default GitHub Pages build pipeline does not support post-build hooks. Use the GitHub Actions workflow above instead of the automatic build.