Setting up the whole thing is not complicated. GitHub guides are easy to follow and the default page comes up in minutes, even when using a custom domain. Local development environment and theme customizations may take a little longer.

Local environment

Following the official installation guide should get the job done. However, if you are an unlucky user of Apple silicon Mac running macOS 12.6 and have Xcode version 14 installed, Ruby installation will fail for version 3.1.2. A workaround for ruby-install users is to add the --enable-shared flag (#430):

% ruby-install 3.1.2 -- --enable-shared

The fix for the issue has been back-ported from Ruby 3.2.0-preview2 to Ruby 3.1 (#6440) and should be released as 3.1.3.

Also missing from the official tutorial is the need for the webrick gem starting from Ruby 3, as explained by Moncef Belyamani:

% bundle add webrick

File locations

Static pages have been moved to _pages following the notes from Michael Rose. Any markdown files left in the site root must be excluded:

# _config.yaml
include:
  - _pages
exclude:
  - README.md

Theme

Default jekyll/minima is one of the cleanest among popular themes on GitHub. Since theme’s gem is long outdated, fetching a development version using remote_theme is recommended. To keep remote theme version under control, it is possible to pin down a specific tag or Git ref:

# _config.yaml
remote_theme: jekyll/minima@41b97699af658128fa9983e5312ca5516641f335

Theme configuration includes a skin selection and social links:

# _config.yaml
minima:
  skin: auto
  social_links:
    github: boxyrobot

Customizations

Theme fonts are replaced with Source Sans Pro and Source Code Pro, sizes and weights slightly adjusted:

<!-- _includes/custom-head.html -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Source+Sans+Pro:wght@400;600&family=Source+Code+Pro:wght@500&display=swap" rel="stylesheet">
// _sass/minima/custom-styles.scss
.site-title, h1 {
  font-weight: 600;
}
pre,
code {
  font-size: 0.875em;
  font-weight: 500;
}
// _sass/minima/custom-variables.scss
$base-font-family: "Source Sans Pro", $base-font-family;
$code-font-family: "Source Code Pro", $code-font-family;
$base-font-size: 18px;

Dates are stripped from the permalinks:

# _config.yaml
permalink: /:categories/:title/

Read time is calculated using Liquid filters following the notes from David Capello and added via a site-specific _layouts/post.html. Reading cadence is set using the words_per_minute site parameter:

# _config.yaml
words_per_minute: 180

Clock-like glyph was found on Graphemica.