PBS 190 of X: Jekyll Wrap-up (Jekyll with GitHub Pages)
We’ve now explored the basics of almost every Jekyll feature. This final Jekyll instalment will explore one last feature (data files), close the loop on a few other loose ends, and then round out the mini-series with an overview.
Matching Podcast Episode
You can also Download the MP3
Read an unedited, auto-generated transcript with chapter marks: PBS_2026_11_21
Worked Examples & Instalment ZIP
Possible Gem Errors
If you check out the example code at a named tag and Jekyll fails to install or run using your preferred method (native Ruby or Docker) with an error containing the following:
jekyll 3.10.0 | Error: unknown keyword: create_additionsReapply the fix instalment 187 by running the following command in the checked-out folder:
bundle add json --version "< 2.8.0"
As a reminder, the worked examples for these Jekyll instalments are built around a demo site versioned in the pbs-jekyll-demoSite GitHub repo. The starting point for this instalment is the commit tagged pbs190-startingPoint. As usual, you can download a ZIP of this commit from GitHub, or fork the repo and then check out the tagged commit on your fork.
For this instalments worked example, you’ll also need to download the instalment’s ZIP file.
Data Files
Different sites exist to publish different kinds of media. Depending on what you’re doing, you may need to publish some kind of data set. If all you want to do is let people download the raw data, then you simply add it as a static file, but if you want to visualise the data in some way, you need to make it accessible within Jekyll. This is what data files are for.
A data set could be anything — it could be a list of rooms in a venue with various pieces of information about those rooms, or a list of products being offered for sale.
If I were building a site for a conference I would want to include a little table about each room in the Markdown page describing each presentation, letting attendees and speakers know the capacity of the room, whether or not there’s a screen, whether there’s table for the attendees or not, whether those tables have power sockets, and so on. I’d add a data file to my site with the information for each room, and connect a specific record in that data file to each talk’s page using the front matter.
Similarly, if I was adding a page to my own website listing some prints I had for sale, I’d add the details in a data file, then loop over them in a custom layout, creating a nice little card for each one with the appropriate information about it.
We’ve seen that we can add any data we like into a site’s configuration file (_config.yml) and access it via the site Liquid variable, so could we not just add our data sets in there? You could, but you’d find that approach quite frustrating as our data sets scale. The site configuration file is simply not intended to be used as a database, so it’s not the right tool for the job!
Jekyll provides a solution just for data sets: the _data folder! You can add as many data sets as you like to this folder, one data set per file, and Jekyll will accept data in the following formats:
- JSON — the file must be saved with
.jsonfile extension - YAML — the file must be saved with a
.ymlor.yamlfile extension - CSV (Comma-separated values) — the file must be saved with a
.csvfile extension and contain a header row. - TSV (Tab-separated values) — the file must be saved with a
.tsvfile extension and contain a header row.
When you add a file to the _data folder, the data within it becomes available through a key under the site.data named the same as the file name without its extension. This means that the content of a file named ./docs/_data/my_data.json is made available as site.data.my_data. This means you must never add more than one data file with the same base name!
If you need to add a lot of data sets, you can nest your data sets in subfolders within the _data folder. The folder names get added into the variable path, so a file saved in ./docs/_data/geo/climate.csv will become available as site.data.geo.climate.
Data files have three advantages over hard-coding data into the site config file:
- Scalability — while small data sets could be added straight into the config file (but don’t), that approach doesn’t scale for larger data sets.
- Data Formats — the site config file is a YAML file, but data files can be formatted in YAML, JSON, CSV, or TSV.
- Watch Mode Support — when developing locally, watch mode allows you to see your changes in near real time, with one exception — configuration file changes. If you add your datasets into the config file, then you need to restart your local instance to pick up any changes you make to your data. Separate data files are fully supported in watch mode, making development that little bit easier.
Worked Example — Nobel Prizes Data Set
When we explored the data querying language and command jq (starting in instalment 155), we made extensive use of the Nobel Prize website’s JSON data set. Since we last used this data set, the Nobel Prize committee have updated their API endpoints, adding a little more information to each entry, including support for more than one language.
You’ll find a snapshot of this data set exported from the free-to-use API URL https://api.nobelprize.org/2.1/nobelPrizes?limit=1000 in the instalment ZIP file as nobel_prizes.json. This file was created with the following terminal command:
curl 'https://api.nobelprize.org/2.1/nobelPrizes?limit=1000' | jq '.nobelPrizes' > nobel_prizes.json
Save this file into your copy of the demo site as ./docs/_data/nobel_prizes.json.
We can now use this data within our site by looping over site.data.nobel_prizes.
Let’s add a special page to our site to list all the Nobel Prizes ever awarded. To do this, we will need a custom layout and a basic page that uses our new layout.
Let’s start by creating the page — create ./docs/nobel_prizes.md with the following content:
---
layout: nobel_prizes
title: The Nobel Prizes
short_title: Nobel Prizes
date: 2026-07-20
more_info_url: https://www.nobelprize.org/about-the-nobel-prize/
---
*"The Nobel Prizes are prestigious international awards established by the will of Swedish inventor Alfred Nobel in 1895 and awarded annually since 1901. They honor outstanding achievements in physics, chemistry, physiology or medicine, literature, peace, and—since 1968—economic sciences. Each laureate receives a gold medal, diploma, and monetary prize, with ceremonies held on December 10th, the anniversary of Nobel's death. Widely regarded as the world's most distinguished recognitions, they celebrate individuals who have advanced human knowledge, promoted peace, and enriched literary culture."* — [Lumo AI](https://proton.me/lumo)
This file contains an editable description of what the Nobel Prizes are, and, some front matter data that our custom layout will utilise:
date— this is a standard Jekyll field that can be added to any page. It gets interpreted as the page’s last-edited date, and can be accessed in layouts aspage.date(just like all other page front matter). The date should be formatted as ISO 8601 (YYYY-MM-DD). We’ll use this field to record the date the data set was last refreshed.more_info_url— a URL linking to an appropriate detailed description of what the Nobel Prizes are.
Note that we are specifying a layout that does not exist yet (nobel_prize). This will cause a warning when the site re-builds, and the new page will initially be created using the default layout.
Let’s now create our custom layout.
Create a file named ./docs/_layouts/nobel_prizes.html with the following content:
---
layout: default
---
<header class="mb-4">
<h1 class="display-1 mb-0">{{ page.title }}</h1>
<p class="my-0"><small class="text-muted">Snapshotted from <a href="https://www.nobelprize.org/about/developer-zone-2/" target="_blank">the Nobel Prize API</a> on {{ page.date | date: "%B %d, %Y" }}</small></p>
</header>
<div class="card mb-4 bg-info-subtle text-info-emphasis">
<div class="card-header">
ℹ️ About {{ page.title}}
</div>
<div class="card-body">
<div class="card-text">{{ content }}</div>
{% if page.more_info_url %}
<a href="{{ page.more_info_url }}" target="_blank" class="card-link link-underline link-underline-opacity-0">More …</a>
{% endif %}
</div>
</div>
<h1>All Awarded Prizes</h1>
<dl>
{%- for prize in site.data.nobel_prizes %}
<dt>{{ prize.awardYear}} — {{ prize.category.en }}</dt>
<dd class="ps-3">
{%- if prize.topMotivation.en %}
<p><strong>Note:</strong> {{ prize.topMotivation.en }}</p>
{%- endif %}
{%- if prize.laureates %}
<ol>
{%- for laureate in prize.laureates %}
<li><strong>{{ laureate.knownName.en | default: laureate.orgName.en }}</strong>{% if laureate.motivation.en %} — {{ laureate.motivation.en }}{% endif %}</li>
{%- endfor %}
</ol>
{%- endif %}
</dd>
{%- endfor %}
</dl>
I want to draw your attention to a few details.
Firstly, this is yet another nested layout within our default layout.
Secondly, the content from the Markdown file is used as the text for an information card describing what the Nobel Prizes are (using the {{ content }} Liquid tag).
Thirdly, the prizes are rendered as an HTML definition list which is built by looping over the Liquid variable site.data.nobel_prizes.
Finally, our layout makes use of the front matter flagged for your attention in the Markdown file (page.date & page.more_info_url).
Allow the site to rebuild, and you’ll see we now have a complete listing of all awarded Nobel Prizes as of July 2026.
Controlling Permalinks
Jekyll provides very sensible defaults for permalinks, but you can assert your own preferences as desired.
Firstly, you can override the permalink for any piece of content using the permalink front matter key.
To see how this works, let’s shorten the URL for our Nobel Prize listing from its default ./nobel_prizes.html to simply ./nobels/ by adding the following to the front matter in ./docs/nobel_prizes.md:
permalink: /nobels/
If the collection your content belongs to uses URL slugs as part of it’s permalink structure, then you can override just the slug for a specific piece of content using the slug front matter key.
In the previous instalment, we learned how to control the permalink structure for any custom collections we create. We can do the same for the built-in taxonomies for pages and posts via the site configuration file.
You can update the structure for the entire site using the site-wide configuration key permalink. This can be useful, but it gets a little confusing to read because you need to add all your desired placeholders for pages and posts into the one template, even though some of those placeholders only exist for some types of content. A better approach is to define the permalink structure at the collection level using the collections dictionary.
To understand how this works, it’s important to know that under the hood, both the pages and posts taxonomies are implemented as collections. This means we can control their permalink structure by adding entries of the following form to the site configuration file, _config.yml:
collections:
pages:
permalink: PATTERN_HERE
posts:
permalink: PATTERN_HERE
The list of supported placeholders is very long, and it varies from taxonomy to taxonomy, but you’ll find all the details in the Jekyll permalink documentation.
Because certain permalink structures are very common, Jekyll provides a few named permalink styles that act as predefined combinations of placeholders. Most notably:
permalink: date→/:categories/:year/:month/:day/:title:output_extpermalink: pretty→/:categories/:year/:month/:day/:title/permalink: none→/:categories/:title:output_ext
Front Matter Defaults
We briefly looked at how front matter defaults in the site config file (_config.yml) work in the previous instalment when we used this feature to apply a specific layout to every entry in the recipes taxonomy. In that instalment our focus was on content collections, so we didn’t look at this useful feature in detail. Let’s now revisit the feature for a deeper description of how it works.
Firstly, the documentation makes it clear that every entry in the defaults array must define the following two top-level keys — scope and values, both of which should be dictionaries. In addition, the scope dictionary must define a path key, and can also add a type key. All other keys will be ignored.
The problem to be solved is defining default values. You define those in the values dictionary. They can be anything you like. Whatever you add inside values will be available in documents; the default gets applied directly within the page dictionary. So values.breakfast becomes page.breakfast, and so on. If a specific file containing content, i.e., one of your Markdown files, defines a different value for a key that has been assigned a default value, then the value defined in the Markdown file takes precedence. In other words, values defined in site.defaults[*].values.* are treated like you would expect default values to be treated!
The purpose of the scope key is to define the scope to which the default values should be applied. In other words, which Markdown files should they apply to?
The scope.path property is interpreted as a folder **within your site’s source **(./docs in our example site), not as a path within the generated website. In other words, to apply a default to all Markdown files saved anywhere under SITE_SOURCE_FOLDER/my_category/_posts, you would set scope.path to my_category/_posts.
This means that all Markdown files saved anywhere within the site can be targeted by explicitly setting scope.path to an empty string.
The documentation also states that the * wildcard character can be used within scopes, but warns that it can have significant performance impacts when rendering complex sites.
And finally, as we learned in the previous instalment, the scope.type property can be used to limit the scope to only Markdown files belonging to specific collections.
We’ll see some examples of how site defaults can be used in the final worked example below.
Worked Example — Revisiting our Metadata Headers
As a quick reminder, we learned about the SEO and social media HTML metadata headers in instalment 186, and we added some basic metadata headers to our demo site in instalment 187.
We added those basic headers before adding a blog to our site, and before adding our custom collections, we should revisit our implementation of these headers to take account of our new, richer information architecture.
The first header that needs some improvement is the OpenGraph page type (<meta property="og:type">). We need to set this to article for blog posts and recipes. Currently we set this header in ./docs/_includes/html_head_common.html with the lines:
{%- if site.meta.og_type %}
<meta property="og:type" content="{{ site.meta.og_type }}">
{%- endif %}
There are many possible ways we could implement the desired overrides, but I’m going to use this as an opportunity to illustrate the use of the page.collection property.
Rather than using a single value in the site config, let’s add our desired customisation directly within the include file.
Replace the lines above with the following:
{%- if page.collection == 'posts' or page.collection == 'recipes' %}
<meta property="og:type" content="article">
{%- else %}
<meta property="og:type" content="website">
{%- endif %}
Since we’re no longer using site.meta.og_type, you can delete the line og_type: website from ./docs/_config.yml.
Restart Jekyll to be sure the updated config file is read, rebuild the site. Using your browser’s developer tools, view the source, and then you can verify that blog posts and recipes get the following header (inside the <head> section near the top):
<meta property="og:type" content="article">
While all other pages, including the blog and recipe indexes, get the header:
<meta property="og:type" content="website">
Next, let’s add some search engine keywords by defining a <meta name="keywords"> tag.
The value for this tag should be a comma-separated list of keywords. It makes sense to build the list for a given page from a number of possible sources, specifically:
- Any categories the item belongs to.
- Any tags assigned to the item.
- Any keywords defined in the item’s front matter as
meta.keywords
We need to build a single list from three possible lists, all of which are optional. Jekyll provides a filter for merging lists, but that filter can’t handle being given a null value, so we need to default each possible source to an empty list with the default filter before we can merge them.
While the latest version of Jekyll supports the direct creation of an empty list, the version of Jekyll GitHub uses does not. However, there is a commonly used workaround that looks a little silly, but works reliably:
{%- assign _empty_array = '' | split: ',' %}
This creates an empty list named _empty_array by splitting an empty string on a comma.
Once we have an empty list we can use it as the default value for each of our three optional lists of keywords. Once we have our three lists, some or all of which could be empty, we can combine them into a final master list using the concat Liquid filter, and remove any duplicates with the uniq filter. If we have any keywords in our final list, we can render them as a comma-separated list with the join filter.
Add the following to the end of ./docs/_includes/html_head_common.html:
{%- assign _empty_array = '' | split: ',' %}
{%- assign category_keywords = page.categories | default: _empty_array %}
{%- assign tag_keywords = page.tags | default: _empty_array %}
{%- assign page_keywords = page.meta.keywords | default: _empty_array %}
{%- assign keywords = category_keywords | concat: tag_keywords | concat: page_keywords | uniq %}
{%- if keywords.size > 0 %}
<meta name="keywords" content="{{ keywords | join: ', ' }}">
{%- endif %}
Allow the site to rebuild, navigate to the blog post about female scientists, and view the page source. You’ll see that the post’s category, science, and tags, scientists & diversity, have all been added as keywords:
<meta name="keywords" content="science, scientists, diversity">
Navigating to the blog listing and viewing the source shows no keywords, let’s add one directly to the page’s front matter.
Open ./docs/blog.md and add the following to the end of the front matter:
meta:
keywords: [ blog ]
Allow the site to rebuild, and view the updated page source. Now notice the page has one keyword:
<meta name="keywords" content="blog">
Let’s do something similar for the recipe index. Edit ./docs/recipes.md and add the following to the end of the front matter:
meta:
keywords:
- recipes
- cooking
- food
Allow the page to rebuild, and view the source to reveal the expected keywords:
<meta name="keywords" content="recipes, cooking, food">
Finally, let’s use front matter defaults to add the same standard keywords to all recipes.
Edit the site config file (./docs/_config.yml) and find the current front matter defaults for the recipes collection:
# Configure front matter defaults
defaults:
- scope:
path: ""
type: recipes
values:
layout: recipe
At the moment, we have one entry that applies to all items anywhere in the site that belong to the recipes collection and sets just one front matter value, page.layout to recipe.
Let’s add another value for page.meta.keywords. Replace the code above with the following:
# Configure front matter defaults
defaults:
- scope:
path: ""
type: recipes
values:
layout: recipe
meta:
keywords:
- recipe
- cooking
- food
Restart Jekyll and rebuild the site, then navigate to our one recipe, the banana pancakes, and view the source to verify we have the expected keywords:
<meta name="keywords" content="recipe, cooking, food">
Jekyll Overview
Now that we’re at the end of our Jekyll journey, let’s quickly summarise the set of features and technologies at your disposal when building a website with Jekyll.
- Jekyll is a static site generator written in Ruby that transforms a collection of source files in a defined folder structure into a rendered website using Jekyll’s rendering process.
- Content is added to sites using three distinct types of files
- Rendered files, generally written in Markdown (though you can use HTML if you prefer). These files should only contain content, and that content can be enriched with the Liquid templating language and the Jekyll Variables. Jekyll processes these files, wrapping them in an appropriate Jekyll Layout.
- Static files, generally images or other media. These files are not processed by Jekyll in any way, and are published unchanged.
- Assets, files that support Jekyll Layouts. These files are compiled from a source language to a destination language. The following two languages are currently supported:
- SASS files get compiled to CSS
- CoffeeScript files get compiled to Javascript
- Metadata and configuration information is expressed in YAML, both in the configuration file, and in front-matter sections at the start of rendered files.
- A site’s look is defined with nested Jekyll Layouts written in HTML and the Liquid templating language using the Jekyll variables.
- Enriched with static files including Javascript, CSS, and images
- Enriched with compiled assets like SASS and CoffeeScript
- Layouts defined by others can be imported into a Jekyll site as a Jekyll Theme, and that theme can be augmented with layouts defined within the site.
- Jekyll Includes are used to define reusable snippets. These snippets can be used for both content and layout, and are written in Markdown or HTML and enriched with the Liquid templating engine and the Jekyll variables.
- A site’s information architecture is defined with taxonomies:
- Two built-in top-level taxonomies — one for regular pages, and one for dated posts.
- Two built-in sub-taxonomies for categories and tags.
- Jekyll Collections can be used to define your own custom taxonomies.
- Permalinks are used to define the URL structure of the rendered site.
- A site’s content can be enriched with information stored in data files formatted in JSON, YAML, CSV, or TSV.
Final Thoughts
Static site generators in general provide a good alternative to real-time content management systems like WordPress for sites that don’t update more than a few times a day. They’re much cheaper and simpler to host because the generated site is purely static, consisting of nothing more than a collection of HTML, CSS, Javascript, and image files. There’s no need for server-side processing, so no need for PHP or similar server-side language, and there’s no database, so need for a MySQL or PostgreSQL server.
There are lots of static site generators available, but Jekyll has the advantage of being supported out-of-the-box on GitHub, allowing for free site generation and hosting on a custom domain with GitHub Pages. You can mange and host a Jekyll site as a GitHub repository, where your content is automatically versioned, the Jekyll build process automatically triggered each time you push a change to your repository, and the generated website immediately availably online.
If you like the concept of a static site generator, but find something about Jekyll doesn’t agree with you — perhaps you find Ruby apps a pain to work with — Hugo is an interesting alternative that’s gaining popularity at the moment (Autumn 2026). Nosillacastaway Eddie Tonkoi published an article and a podcast segment describing his use of Hugo to build a website in November 2025.