Deploying Jekyll + al-folio to Cloudflare Pages

While I have built my personal websites with Jekyll for years, I recently decided it was time for a visual overhaul. I was fortunate to stumble upon al-folio, a powerful Jekyll theme designed for academics. The theme includes GitHub Actions workflows that enable automated building and deployment to GitHub Pages, but I was interested in deploying the site to Cloudflare Pages.

Update — October 4, 2026: This post documents the deployment workflow I used in 2024 and is retained for historical context. The cloudflare/pages-action@v1 action is no longer available, and the broken-links → workflow_run arrangement described below no longer matches current al-folio workflows. See the updated guide for the current GitHub Actions and Wrangler approach. The gist of the modified deploy.yml workflow is still available, although it should not be copied into a new workflow.

Installation

This guide assumes you created your project from the al-folio repository template. Other installation methods are available, but this is the approach recommended by the developers.

First Attempt

Cloudflare Pages includes a Git integration that enables automated builds and deployments based on specified branch triggers. Unfortunately, the Jekyll build environment available within the integration was not able to build the site. Why? It turns out that Jupyter was the culprit. The al-folio theme uses Jupyter to convert ipynb snippets and notebooks into HTML, but the default Cloudflare Pages Jekyll build environment does not include a Jupyter installation.

Solution

Rather than build the site on Cloudflare, I made a few changes to al-folio’s included GitHub Actions workflows so they would build the site and deploy the generated assets to Cloudflare.¹

1. Use Cloudflare’s Git integration guide to create an account and connect your repository to Cloudflare Pages.

2. In your project’s repository, modify the .github/workflows/deploy.yml workflow, replacing the github-pages-deploy-action action with Cloudflare’s pages-action.

   - name: Publish to Cloudflare Pages
     uses: cloudflare/pages-action@v1
     with:
       apiToken: # Cloudflare API token
       accountId: # Cloudflare account ID
       projectName: # your Cloudflare Pages project name
       directory: _site
   

   • Secure your workflow by storing apiToken and accountId values as repository or organization Secrets.

Multiple Deployments

It is possible to use both production and preview deployments in Cloudflare Pages.²

1. Update the .github/workflows/broken-links.yml workflow to include the desired development branch(es). This workflow’s successful completion triggers the deploy.yml workflow.
   • In Cloudflare, navigate to Workers & Pages > your_project > Settings > Builds & deployments.
   • Under Configure Production deployments, disable automatic deployments.
   • Under Configure Preview deployments, set Preview branches to None.

2. Modify your repository’s .github/workflows/deploy.yml workflow to include branch information.³

   steps:
     - name: Checkout
       with:
         ref: ${{ github.event.workflow_run.head_branch }}
     - name: Publish to Cloudflare Pages
       with:
         branch: ${{ github.event.workflow_run.head_branch }}
   

Conclusion

You should now be able to access your site through Cloudflare Pages. Cloudflare may mark the project as Deployments paused because its own build system is disabled; GitHub Actions is now responsible for building and deploying the site. A gist of the updated deploy.yml workflow is available here.

---