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 simple yet powerful theme designed for academics. The theme includes GitHub Actions workflows which enable automated building and deployment to GitHub Pages, but I was interested in deploying the site to Cloudflare Pages.

Installation

This guide assumes the al-folio repository is used as the template for your project’s repository. This is not the only way to apply the theme, but is recommended by the developers.

First Attempt

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

Solution

Instead of building the site on the Cloudflare platform, we can utilize, with a few modifications, the GitHub Actions workflows included with the al-folio template to build and deploy the site assets to Cloudflare.¹

1. Use Cloudflare’s Git integration guide to create a Cloudflare account and link a GitHub repository within Cloudflare Pages.
2. 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
   

   • Reference the pages-action documentation for steps to create an API token.
   • Secure your workflow by storing apiToken and accountId values as repository or organization Secrets.

Mutiple Deployments

It is possible to utilize 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
   • Disable Automatic deployments in the Configure Production deployments
   • Set Preview branches to None in Configure Preview deployments
2. Modify the .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 }\}
   
    # Remove the backslashes preceeding the curly braces around github.event.workflow_run.head_branch.
    # They were added to mitigate autoescaping in this post.
   

Conclusion

You should now be able to access your site through Cloudflare Pages! You may notice the status of your project in the Cloudflare Pages Overview marked as Deployments paused, but don’t worry; that status references the fact you disabled building your Jekyll project on the Pages platform itself.

A gist of the updated deploy.yml workflow is available here.

---