Better GitHub Pages experience with Jekyll

Share
#1

Hey y’all. Congrats on 4.0 and thanks for having the forum. Spent the past few days on here and stackoverflow getting some of my sites updated and they’re finally done! I saw posts like this one /github-pages-and-jekyll-4-0-0/3471 (sorry i can only put two links in a post I’m new) who are upset that GitHub Pages is missing a lot of features which bottlenecks Jekylls potential.

Just wanted to share some articles I wrote on how to bypass GitHub Pages limits entirely and use Jekyll with all of the latest features available. I also wrote a bit more in depth on how to add super simple automated static-site testing to make sure my deployments are mostly never broken.

TL;DR
Using any devops tools like Jenkins, CircleCI, GitHub actions allows you to add a layer of automation between your commits and deployment. That layer is simply automating one of those platforms to build the site source, and then push it as a commit to a separate branch on GitHub where it will publish it exactly the same as if you had let GitHub do the build. The different is in the CI environment you have control over everything. the jekyll version. the plugins. using other gems to manipulate the site source, or do other quality checks. It’s not exactly a novel idea, but I’ve included a CircleCI example config that you can copy/paste as well as code snippets for running some basic QA checks on your produced source files. which you can run locally as well.

Any feedback on the articles is surely appreciated as well!

#2

Thanks for sharing. I am going to check them out.

Unfortunately as far as I can tell, Github Pages chooses 3.8.x for you and this cannot be overridden with Gemfile or config. https://pages.github.com/versions

I switched one of new projects to jekyll 4 by specifying it in Gemfile and doing a Netlify build.

I use Netlify for some projects rather than Github Pages. One reason is the build log is verbose and I have control over the build command. Also there is a rebuild button which does not require a commit. You can share the build log with others if set to public and you can build Pull Requests as deploy previews which I found super useful lately.

#3

Plus in Netlify you can could specify tests as part of the build command.

I recently also found a Ruby gem which I ran locally to check for any broken links on a site and potentially this could be added as part of a deploy workflow.

#4

I may have explained it poorly. The method I describe in the blog posts outline how you can avoid the limitations of GitHub Pages by using CircleCI to build the site with Jekyll in CI and then publish the fully built site to GitHub Pages. And in the CI environment you can use Jekyll 4.0 and anything else. I’ve added some very basic QA validation as well that prevents the site from being deployed with errors that can hurt SEO or UX.

#5

Okay I see. So your code is on one branch and built site on another, or different repos? I saw something for react which compiles and builds and publishes to different branch so one can use something not normally possible on GH pages.

#6

Yes, in GitHub pages you can have the source code live in the master branch, for instance, and build/push the website to a separate branch. Then you tell GitHub to serve from the branch with the fully built site rather than the source. and you can use any version of Jekyll, or any gems/plugins that are available without issue but still host on GitHub pages.

#7

What tells GitHub to serve from the gh-pages branch versus the master branch? I have a user site <user>.github.io and it looks like the settings page says it can only be served from master for User pages. But I have set my gh-pages branch as Default – I think this just means this is the branch that it shows when someone visits the repo and/or downloads/clones it for the first time.

#8

There are settings on GitHub to configure for this. Check their docs…

https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site

#9

You could maybe even simplify matters by using GitHub Actions directly instead of CircleCI. I’m not sure if GH Actions makes it easy to commit changes to another branch as part of the workflow, but if so that’d be a pretty nifty setup.

#10

Yesterday I finished a tutorial which is doing on Jekyll site for using Github Actions, GH Pages and Jekyll 4.

Check the link in the PR summary for preview URL.

When its merged you can find Github Actions added to this list

The way the deploy works in this case is using code on master and then committing and serving on gh-pages branch.

1 Like
#11

That’s dope. GitHub Actions would totally work as well. Any CI would work really but I had the most experience with CCI so I went with that. But I think GHA is probably easier given the goal here. Nice docs!

1 Like