When deciding on a straightforward solution for generating these articles, I settled on Jekyll for two reasons; firstly, it’s a Ruby project. Secondly, support for it is built in to GitHub Pages, which I was already using for hosting this site.
Getting started
Jekyll is most easily installed as a Ruby gem:
gem install jekyll
To get a new Jekyll project started, you can use the built-in generator to scaffold up the basic directory structure:
jekyll new my_project
tree my_project
# my_project
# ├── 404.html
# ├── Gemfile
# ├── Gemfile.lock
# ├── _config.yml
# ├── _posts
# │ └── 2024-02-18-welcome-to-jekyll.markdown
# ├── about.markdown
# └── index.markdown
You can then run jekyll serve to have Jekyll watch the directory, continuously build static HTML into _site/, and serve it on port 4000.
Back to basics
The scaffold includes some configuration and theming that I didn’t want to dive right in with, given I was hoping to add to an existing site. Instead, I added a minimal Gemfile to project, as well as an empty _config.yml file, and copied over the sample markdown post into a _posts directory.
Using Liquid
Jekyll uses the Liquid templating engine, and will generally treat any file with frontmatter as a template, and process tags such as {{ this }} and {% this %}. For example:
---
title: A descriptive title for this page
---
<html>
<head>
{% if page.title %}
<title>{{ page.title }}</title>
{% endif %}
</head>
...
</html>
Check out the documentation for more details on flow control, iteration, any the many built-in filters.
Using layouts
Jekyll has two mechanisms for code sharing; the first are “layouts” (sourced from _layouts), which can be nested, and are requested via the front matter:
<!-- _layouts/main.html -->
<html>
<head>
...
</head>
<body>
{{ content }}
</body>
</html>
---
layout: main
---
<!-- index.html -->
<h1>Welcome to my site</h1>
Using includes
The other mechanism for reuse are “includes”. These are found in _includes/ and can have their contents evaluated and injected in other pages. As an example, a template for creating a reusable <figure> can be defined as follows, referencing passed arguments via include.:
<!-- _includes/figure.html -->
<figure>
<img alt="{{include.alt }}" src="{{include.src }}">
<figcaption>
{{include.caption }}
</figcaption>
</figure>
It could then be used in any other templated page by naming parameters:
<!-- _posts/2024-01-01-photos-from-my-trip.html -->
{%
include figure.html
alt="A view looking out over the ocean as the sun sets"
src="/assets/images/holiday.jpeg"
caption="What a great view!"
%}
Writing posts
Posts are authored in dated template files held in _posts, although Jekyll also supports a _drafts directory too; here, each file’s mtime is used to set the post’s date. Draft posts are not generated by default; you need to use jekyll serve --drafts to include them.
Jekyll exposes generated posts via the site.posts variable, which can then be manipulated using Liquid. Similarly, if posts are tagged using tags: ... in their front matter, site.tags returns a list of tags with their associated posts. I used these to create listing pages of both posts and tags.
Wrapping up
Whilst not being the most fully-featured solution, I’ve found Jekyll+Liquid to be straightward to work with, and the support built in to GitHub Pages makes deploying a breeze; you literally just push to your deploying branch and GitHub Actions does the rest.
I’d encourage you to give it a try, and to check out the full source for this site if you like!