Jekyll, GitHub pages and the JAMStack

by Zoja Savkovic

I have another blog at memoriesandrecipes.com and have always wanted to write up how it is put together behind the scenes.

The end user viewing the blog is served static html and some other resources. The blogger checked in some markdown, pictures and maybe a few other things in to a GitHub repository. That's it. No database or server are used by the blogger. The rest is the magic that is explained below.

In summary I'll cover:

  • GitHub Pages: which is like a static site hosting service which serves HTML, CSS and JavaScript.
  • Jekyll: the HTML, CSS and JavaScript that are served, were created by Jekyll, a static site generator.
  • How to run Jekyll, just to understand it a bit more.
  • What stack this is - the JAMstack.

Let's start at the user - they are served a page by GitHub pages.

So What are GitHub Pages

The simple explanation is that GitHub Pages is simply a plain old static site hosting service. Static sites are fast since there’s no server processing time involved. You essentially serve your entire website from the cache. Any HTML, CSS and JavaScript in a repository's specifically named "gh-pages" branch, are magically served at a URL like https://username.github.io/repositoryname .

The drawback with GitHub Pages is that other people can view all the files in your site, although often this can be a good thing.

GitHub Pages is serverless and doesn’t allow server-side code, so you’re limited to HTML, CSS and JavaScript. Note that everything that's serverless still has a server. Serverless just means that the developer does not need to do server management themselves.

So you can paste HTML, CSS and JavaScript in to a repository, that's easy. Those can come from any static site generator, like Jekyll or Hugo, that you run yourself to get the files. You'll have to paste those HTML, CSS and JavaScript files that are generated, in to a repository to host them.

But Jekyll is special for GitHub Pages. You can commit files in a repository with certain Jekyll (more on that below) folder structures and files, to have GitHub pages use Jekyll to build those HTML, CSS and JavaScript for you, at commit time, so that you don't have to manually do it.

So, in addition to being a static site hosting service, GitHub Pages is also a third party deployment provider for Jekyll.

GitHub Pages also takes care of an SSL certificate for you - you can enforce HTTPS in your repository’s settings. They partner with Let's Encrypt for this.

So GitHub Pages is pretty much a "system" - it's a system built into GitHub that allows you to have websites generated by Jekyll built for you at commit time, from a GitHub repository, and served over HTTPS.

So a blogger just needs to check in something in to a repository, to publish a post!

But What is Jekyll

As for what is checked in as a post when using Jekyll - it can be a markdown file and assets such as images. These will be in a certain folder structure.

Jekyll then uses things like HTML templates and CSS styles you give it in a certain folder structure to generate your site. There are other static site generators like Hugo (written in Go) and Octopress.

Jekyll differs from a Content Management System (CMS) like WordPress, where users enter text in to a WordPress console, which is stored in a database. With Jekyll, the text is entered in to, and stored in a markdown file. CMS pages are usually compiled to active pages (not static pages).

Jekyll is sort of half way between a CMS and writing your own static HTML.

Jeykll allows you to use languages such as Markdown or Textile. It allows for more advanced templating than HTML gives you on its own, using Liquid for pre-processing.

There are obviously other options for deploying a Jekyll site other than on GitHub Pages, such as:

  • manually, by hosting the generated "_site" folder with any hosting provider
  • automated
  • third party, eg GitHub Pages and Netlify

Running Jekyll

Just to understand Jekyll a bit more and get in to the details, let's understand how to run it - how to take HTML templates and CSS styles, and end up with static HTML.

Jekyll is a Ruby library, a Ruby "gem". So to run Jekyll, you need to install Ruby.

You can use bundler to install the "gems" in your Gemfile. It’s not a requirement for you to use a Gemfile and bundler however it’s highly recommended as it ensures you’re running the same version of Jekyll and Jekyll plugins across different environments.

Gemfile.lock locks the current gem versions for a future bundle install. This restricts your Ruby environment to only use gems set in your Gemfile. If you ever want to update your gem versions you can run bundle update.  GitHub have provided the github-pages gem which is used to manage Jekyll and its dependencies on GitHub Pages. Using it in your projects means that when you deploy your site to GitHub Pages, you will not be caught by unexpected differences between various versions of the gems.

When using a Gemfile, you’ll run commands like "jekyll serve" with "bundle exec" prefixed. So the full command is: "bundle exec jekyll serve" - and that's it, how to run Jekyll!

Well, you must also use a given folder structure, and paste content in to .md (markdown) files. You then run Jekyll and it generates pages for you to a _site folder.

The site is going to be static from the point of view of the server, but you can include any JavaScript code and build a whole client-side application on that site.

Without getting in to too many details, the liquid template language is also a Ruby library - for template rendering. It can be used with Jekyll.

Which Stack is that?  The JAMstack?

So we now understand Jekyll and GitHub Pages. But what would this stack be called? It can be called the JAMstack - "A modern architecture - Create fast and secure sites and dynamic apps with JavaScript, APIs, and prerendered Markup, served without web servers."

So that's it! Everything has been covered, from the user seeing the page in their browser, to how the blogger creates their content. Check out  memoriesandrecipes.com and see what you think!