Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

wax_tasks 🐝

ci:test Depfu Gem Version Gem Downloads docs

Maintainability Test Coverage License

wax_tasks is gem-packaged set of Rake tasks for creating minimal exhibition sites with Wax.

It can be used to:

Getting Started


You'll need Ruby >= 3.2 with bundler installed. Check your versions with:

$ ruby -v
  ruby 3.2.2 (2023-03-30 revision e51014f9c0) [arm64-darwin22]

$ bundler -v
  Bundler version 2.4.16

To use the image derivative tasks, you will also need to have ImageMagick and Ghostscript installed and functional. You can check to see if you have ImageMagick by running:

$ convert -version
  Version: ImageMagick 7.1.1-12 Q16-HDRI aarch64 21239
  Copyright: (C) 1999 ImageMagick Studio LLC
  Features: Cipher DPC HDRI Modules OpenMP(5.0)
  Delegates (built-in): bzlib fontconfig freetype gslib heic jng jp2 jpeg jxl lcms lqr ltdl lzma openexr png ps raw tiff webp xml zlib
  Compiler: gcc (4.2)

... and check Ghostscript with:

$ gs -version
  GPL Ghostscript 10.01.2 (2023-06-21)
  Copyright (C) 2023 Artifex Software, Inc.  All rights reserved.

Next, you'll need a Jekyll site. You can clone the minicomp/wax demo site or start a site from scratch with:

$ gem install jekyll
$ jekyll new wax && cd wax


Add wax_tasks to your Jekyll site's Gemfile:

gem 'wax_tasks'

... and install with bundler:

$ bundle install

Create a Rakefile with the following:

spec = Gem::Specification.find_by_name 'wax_tasks'
Dir.glob("#{spec.gem_dir}/lib/tasks/*.rake").each { |r| load r }


After following the installation instructions above, you will have access to the Rake tasks in your shell by running $ bundle exec rake wax:taskname in the root directory of your Jekyll site. To see the available tasks, run

$ bundle exec rake --tasks

Sample site _config.yml file:

# basic settings
title: Wax.
description: a jekyll theme for minimal exhibitions
url: ''
baseurl: '/wax'

# build settings
permalink: pretty # optional, creates `/page/` link instead of `page.html` links

# wax collection settings
  objects: # the collection name
    layout: 'iiif-image-page'
    output: true # this must be true for your .md pages to be built to html!
      source: 'objects.csv' # path to the metadata file, must be within '_data'
      source 'source_images/objects' # path to the directory of source images, must be within '_data'

# wax search index settings
    index: 'js/lunr-index.json' # where the index will be generated
    collections: # the collections to index
        content: false # whether or not to index the markdown page content (below the YAML)
        fields: # the metadata fields to index
          - 'label'
          - 'artist'
          - 'location'
          - 'object_type'

The above example includes a single collection objects that comprises:

  1. a CSV metadata:source file (objects.csv), and
  2. a images:source directory of image and pdf files.

For more information on configuring Jekyll collections for wax_tasks, check out the minicomp/wax wiki and

Running the tasks


Takes a CSV, JSON, or YAML file of collection metadata and generates a markdown page for each record to a directory using a specified layout. Read More.

$ bundle exec rake wax:pages collection-name


Generates a client-side JSON search index of your site for use with ElasticLunr.js. Read More.

$ bundle exec rake wax:search search-name


Takes a local directory of images and pdf files and generates a few image derivatives (i.e., 'thumbnail' 250w and 'full' 1140w) for Jekyll layouts and includes to use. Read More.

$ bundle exec rake wax:derivatives:iiif collection-name


Takes a local directory of images and pdf files and generates tiles and data that work with a IIIF compliant image viewer like OpenSeaDragon, Mirador, or Leaflet IIIF. Read More.

$ bundle exec rake wax:derivatives:iiif collection-name


Destroys (or "clobbers") wax-generated files, i.e., pages generated from wax:pagemaster, derivatives generated from wax:derivatives, and search indexes generated with wax:search so you can start from scratch.

This task does not touch your source metadata or source image files! Instead, it simply clears a path for you to regenerate your collection materials in case you add/edit source materials.

$ bundle exec rake wax:clobber collection-name


Fork/clone the repository. After making code changes, run the tests ($ bundle exec rubocop and $ bundle exec rspec) before submitting a pull request. You can enable verbose tests with $ DEBUG=true bundle exec rspec.


The gem is available as open source under the terms of the MIT License.