Replace Jekyll on Github Pages

If you're switching from Jekyll to something else on Github Pages, this worked for me.

Contents


Edit Your Repo

I suggest you do these changes in a new branch, testing locally to make sure everything builds properly.

On your local:

  1. Pull the repo
  2. Update your content
    1. If you're switching to Hugo you can find a good write-up here: https://blog.arkey.fr/2020/04/20/migrating-from-jekyll-to-hugo-deploying-with-github-pages/
    2. Remove all the Jekyll configuration files / cruft
    3. Add any configuration files you need for your new page builder
    4. Create a blank .nojekyll file in the root of the repo
  3. Create a new file: /.github/workflows/your-action-name.yaml for your new workflow
    1. If you're switching to Hugo you can find information here: https://github.com/marketplace/actions/hugo-setup
  4. Commit your changes but don't merge yet

Delete Jekyll

Once you have a branch that's been tested with your new page builder (Gatsby, Hugo, etc.) ready to go, you can go ahead and change settings on the Github end of things.

Note: When you're done this part your Github pages will be gone and you'll get 404's when visiting the site.

On Github:

  1. Open the repo
  2. Click Settings
  3. Click Pages
  4. Under Build and deployment, click the Configure button on the Jekyll entry
  5. This will open a create action page, rename it to whatever you want, leave the body blank and click Save
    • This will cause build errors, this will be fixed when you merge your new branch
  6. Click Actions, delete all previous workflow runs
  7. Merge your new branch - this should trigger a new build using the action you created in the Edit Your Repo step

Environment Protection Rules Error

If you get a Branch "main" is not allowed to deploy to github-pages due to environment protection rules error, this is easily fixed.

On Github:

  1. Open the repo
  2. Click Settings
  3. Click Environments
  4. Under Deployment Branches, make sure your branch is "allowed"