That Randy Brown

Deploying Eleventy to GitHub Pages

I recently (as in over the last week) converted my GitHub pages site to eleventy using the eleventy base blog. Before that, it was just vanilla HTML and a little bit of CSS. In the conversion, I had a few requirements:

  1. That the page would display as normal until I actually wrote something.
  2. That the workflow works like it does for a vanilla HTML and CSS site.

The first requirement was fairly straight forward. I had to modify a few pages and templates, but getting it to not show a menu if there were no posts was easy enough. However, when it came to deployment, the default pages workflow built the site, and then pushed it to a gh-pages branch, which then I had to update settings to track that branch instead. This isn't a bad flow--in fact, it's used by lots of build based workflows. It's just not the flow I wanted.

There's some great prior art to avoid this approach, specifically by following the Jekyll build pages documentation. GitHub maintains two useful actions that help with a more standard 'push to main, build, and deploy' based workflow: Upload Pages Artifact and Deploy Pages. I swapped the proposed flow by eleventy for these:

-      - name: Deploy
-        uses: peaceiris/actions-gh-pages@v3
-        if: github.ref == 'refs/heads/main'
-        with:
-          github_token: $
-          publish_dir: ./_site
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4

This change allows me to push my code to my default branch and have it deploy. Some magic on GitHub's side automatically detected the change in deployment patterns and toggled my repo settings appropriately, and now I don't have another canonical and long-lived branch to maintain that I didn't want, with the trade-off being that I can't 'checkout' the current built artifact for inspection, and I'll have to download it instead.