Keywords for Black Louisiana

The public Jekyll site for the documents in the K4BL project. See our project overview for general information about the project!

Prerequisites

• Ruby 2.7.x
• imagemagick - used to (locally) generate image derivatives

Please refer to the Wax installation instructions to setup your development environment.

Technology Used

• Wax Facets - a Jekyll theme based on the Wax theme. This includes the following
  • Bootstrap 4 for styling

Local Development

Our site is built automatically in GitHub whenever a change is made to the main branch and deployed using GitHub Pages. Because of the way Wax generates pages and images, we need to keep the Wax generated files out of GitHub so they can be regenerated by GitHub in order to ensure the most up to date content appears on the site. This means that developers will need to also generate these files locally during development and manually keep them up to date as needed.

All commands below are run on the command line (bash or zsh work).

Wax tasks

Generate pages for our data:

bundle exec rake wax:pages keywords
bundle exec rake wax:pages keywords_descriptions

Generate search index:

bundle exec rake wax:search main

Generate image derivatives:

bundle exec rake wax:derivatives:iiif keywords

Running the script to generate image derivatives requires that you have imagemagick installed on your computer.

Also note that the IIIF image derivative script here will modify _data/keywords.csv by appending image related URLs as new columns, or modifying those columns as needed. Those changes should be captured in git, but don't strictly need to be captured.

Jekyll

After you have the Wax tasks run and all of the Wax files generated successfully, we can use Jekyll to run the site locally so you can see the changes as you develop the site.

bundle exec jekyll serve

You should get output similar to the following to know that Jekyll is working. You'll then be able to navigate to http://localhost:4000/ to view your local develompent site.

Configuration file: /home/john/workspace/keywords/keywords/_config.yml
           Source: /home/john/workspace/keywords/keywords
      Destination: /home/john/workspace/keywords/keywords/_site
Incremental build: disabled. Enable with --incremental
     Generating... 
          Warning: Empty `slug` generated for ''.
                   done in 1.808 seconds.
Auto-regeneration: enabled for '/home/john/workspace/keywords/keywords'
   Server address: http://127.0.0.1:4000
 Server running... press ctrl-c to stop.