WIP: scaffolding for adding Wax to existing Jekyll site

[pbinkley]

Work in progress! Needs clean up.

This is a pair of new rake tasks and a payload of files, used to provide scaffolding for Wax in a Jekyll site. The intention is to make it easier to get Wax working with a user's own content than is the case with the default Wax installation, especially for users who already have a Jekyll theme they want to keep. It should also be useful in teaching, where the class starts with basic Jekyll instruction and then moves on to Wax.

Instructions: this shell script will deploy into a fresh Jekyll site, from a local clone of this branch. The script assumes you have downloaded the sample image into your Downloads folder, and you need to set the path to your clone in $TASKS.

#!/usr/bin/bash
export TASKS=/home/pbinkley/Projects/wax/wax_tasks-pbinkley-fork
rm -r scaffold-test
jekyll new scaffold-test
cd scaffold-test
cat << EOF >> Gemfile
group :development do
  gem "wax_tasks", path: "$TASKS"
  gem "byebug"
end
EOF
bundle
cp $TASKS/wax-framework/Rakefile ./
bundle exec rake wax:scaffold:resources
bundle exec rake wax:scaffold:collection my_coll
# Provide some test content
# Image source: https://ia800702.us.archive.org/10/items/BifDS-B6_4/b6_4_r.jpg
cp ~/Downloads/b6_4_r.jpg _data/raw_images/my_coll
echo -e "b6_4_r,Pianta in piano della città di Fano" >> _data/my_coll.csv
bundle exec rake wax:pages my_coll
bundle exec rake wax:derivatives:iiif my_coll
bundle exec jekyll s

Note the two new tasks:

• wax:scaffold:resources copies basic layout, include, assets, Rakefile, etc. from the gem into the Jekyll site, and updates the _config.yml with the CORS stanza.
• wax:scaffold:collection creates a new collection, adding the appropriate stanza to collections in _config.yml and the appropriate directories in _data, and creates a stub metadata csv. For simplicity it assumes each image will have only one field: label; the layouts and includes in the resources payload make the same assumption.

Notes:

• should maybe move the resources task into its own gem and rewrite it as a Jekyll plugin rather than a Rake task, so that it can install the Rakefile needed for all the other Wax tasks. It includes about 2mb of payload (cribbed from the default Wax site), so it would be nice to be able delete it once you've run it once in a project
• The collection task would be handy to have around, so I think it would be worth adding to wax_tasks
• The updating of _config.yml is clumsy due to the desire not to lose comments, which would happen if we just parse the YAML and write it out again. Updates to collections will still cause any comments in that section to be lost. This needs more testing.
• Deploying the scaffolding payload overwrites existing files. This is fine in a default Jekyll install, but may mess up a themed site, by overwriting files like _includes/head.html. The best approach in those cases would be to add the scaffolding in a branch and run diffs to see what it changed. It needs more testing to see whether this is more trouble than it's worth for complex sites, or whether the deployment could be refined to change existing files with only what Wax needs.
• The collection task could take an argument containing a directory path where it can get images to include in the collection; it could then add the appropriate rows to the csv stub
• and of course it needs specs