Shell.nix for GitHub Pages development

Development
1

I want to do local development of a GitHub Pages site. GitHub Pages serves your site using Jekyll, which is written in Ruby. The exact dependencies are listed at

Dependency versions | GitHub Pages

and available as JSON on

https://pages.github.com/versions.json

The dependencies (apart from Ruby itself) are also available as a Ruby package (“gem”):

GitHub - github/pages-gem: A simple Ruby Gem to bootstrap dependencies for setting up and maintaining a local Jekyll environment in sync with GitHub Pages

Given this, is there a simple shell.nix automatically giving a local development environment matching the environment GitHub Pages runs on?

At the very least, if one gives up on automatically keeping up with the Ruby version used by GitHub Pages, then Ruby together with pages-gem should suffice. It is however not clear to me how to accomplish this.

I looked at

Packaging/Ruby - NixOS Wiki

and I also looked at

Building a Jekyll Environment with NixOS

As far as I can see, those approaches generate a shell.nix (and additional files) fixing a development environment on whatever is specified by the current version of pages-gem. Thus when pages-gem is updated this development environment would become outdated. And in any case, ideally one should not need to deal with the large auto-generated Gemfile.lock and gemset.nix files since basically the desired development environment is fully specified by the two lines in the Gemfile file.

2

direnv is your friend in this - in your repository, create the following files:

.envrc:

use nix
layout ruby

Gemfile:

source 'https://rubygems.org'

gem 'github-pages'

shell.nix:

with import <nixpkgs> {};

stdenv.mkDerivation {
  name = "env";

  buildInputs = [
    bashInteractive
    libxml2
    zlib
  ];

  nativeBuildInputs = [
    bundler
  ];
}

Then simply run bundle install and you’re off to the races.

If github-pages changes, you run bundle update.

3

Thanks! I had to add ruby to buildInputs but then this worked like a charm. On MacOS this seems to require XCode development tools. Any way around this? (The approaches I mentioned above works on MacOS without XCode development tools installed.)

(I would still be interested in a “more pure” nix-shell solution.)

4

I solved this by adding libxslt and pkgconfig to the buildInputs.

5

Consider adding your solution to: GitHub - nix-community/nix-environments: Repository to maintain out-of-tree shell.nix files (maintainer=@mic92)
So future people having an easier time to get something working.

6

You should be okay with just “nix-shell -p jekyll”, unless you specify a plugin that is not packaged already.

I mean, all the ruby parts about a github page are dealing with installing and configuring jekyll

7

We’re using the following for https://blog.hercules-ci.com

{ pkgs ? import ./nixpkgs.nix
}:

with pkgs;

stdenv.mkDerivation {
  name = "blog.hercules-ci.com";

  src = lib.cleanSource ./.;

  buildInputs = [
    (jekyll.override { withOptionalDependencies = true; })
    glibcLocales
  ];

  LANG = "en_US.utf8";

  buildPhase = ''
    jekyll build
  '';

  installPhase = ''
    mkdir -p $out
    cp -R _site/* $out
  '';
}