wax_tasks 🐝

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

It can be used to:

• generate collection markdown pages from a metadata file (wax:pagemaster)
• generate a client-side search index (wax:lunr)
• generate either IIIF-compliant derivatives (wax:derivatives:iiif) or simple image derivatives (wax:derivatives:simple) from local image and pdf files

.. and more.

Getting Started

Prerequisites

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

$ ruby -v
  ruby 2.4.2p198 (2017-09-14 revision 59899) [x86_64-darwin15]

$ bundler -v
  Bundler version 1.16.1

To use the IIIF task, 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 6.9.9-20 Q16 x86_64 2017-10-15 http://www.imagemagick.org
  Copyright: Š 1999-2017 ImageMagick Studio LLC
  License: http://www.imagemagick.org/script/license.php
  Features: Cipher DPC Modules
  Delegates (built-in): bzlib freetype jng jpeg ltdl lzma png tiff xml zlib

... and check Ghostscript with:

$ gs -version
  GPL Ghostscript 9.21 (2017-03-16)
  Copyright (C) 2017 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

Installation

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 }

Usage

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.

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
collections:
  objects: # the collection name
    layout: 'iiif-image-page'
    output: true # this must be true for your .md pages to be built to html!
    metadata:
      source: 'objects.csv' # path to the metadata file, must be within '_data'
    images:
      source 'source_images/objects' # path to the directory of source images, must be within '_data'

# wax search index settings
lunr_index:
  - file: 'js/lunr-index.json' # where the index will be generated
    collections: # the collections to index
      objects:
        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 https://jekyllrb.com/docs/collections/.

Running the tasks

wax:pagemaster

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:pagemaster collection-name

wax:lunr

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

$ bundle exec rake wax:lunr

------------------------------------------------------------------------
NOTE >> wax:lunr will also generate a default lunr UI to use
        if you add a ui path to your lunr index configuration
        with `ui: 'example/path-to-ui.js'` and run:

        $ bundle exec rake wax:lunr UI=true
------------------------------------------------------------------------

wax:derivatives:simple

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

wax:derivatives:iiif

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

wax:test

Runs htmlproofer on your compiled site to look for broken links, HTML errors, and accessibility concerns. Runs Rspec tests if a .rspec file is present. Read More.

$ bundle exec rake wax:test

Contributing

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.

Note: The cannonical repository is minicomp/wax_tasks. Please submit all issues and pull requests to the minicomp/wax_tasks repo.

---------------------------------------------------------------------------
NOTE >> The cannonical repository is minicomp/wax_tasks.
        Please submit all issues and pull requests to the cannonical repo.
---------------------------------------------------------------------------

minicomp/wax_tasks ~>

License

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