Tools for hugo

I currently try to write in two types of blogs, one (this) which mainly contains my thoughts on tech and what I do for work and one “personal” blog which mainly contains images.

Both of these pages uses hugo and both of them requires some amount of extra tools and scripts to facilitate easy writing and publishing. This post will simply go through the workflow I use to create graphs and image galleries. All of the short-codes and scripts I use is available at github.

The generation of both graphs and galleries have become a lot easier with the addition of:

{{ $data := getJSON $url }}
into the hugo generator, this allows for easy storage of the “setup” data in json files which can be generated elsewhere.

Graphs

The generation of graphs is fairly straightforward and it is accomplished by a simple although fairly verbose short-code, which takes a json object and generates the javascript required to display the graph. Since I am trying to avoid any unnecessary library dependencies I use chart.js which is self contained and fairly small, while still providing a lot of features.

Since the charting library is self contained the issue of “on page” placement is somewhat minified, however it’s not completely removed and the script will load at the location the chart which might cause slow rendering with very large charts.

With the graphing short-codes (currently only for bar and line charts) and a json document containing the chosen data and any options that you wish to overwrite (docs) generating a new graph become a simple matter of providing the correct path.

{
    "data":{
      "labels": ["Jekyll", "Hugo", "Wintersmith"],
      "datasets": [
          {
              "label": "Mean build time",
              "fillColor": "#E1EDD7",
              "strokeColor": "#E1EDD7",
              "highlightFill": "#C1D8AB",
              "highlightStroke": "#C1D8AB",
              "data": [784, 100, 5255]
          }
      ]
  },
  "options": {
      "scaleBeginAtZero" : true,
      "scaleShowGridLines" : true,
      "scaleGridLineColor" : "rgba(0,0,0,.05)",
      "scaleGridLineWidth" : 1,
      "barShowStroke" : true,
      "barStrokeWidth" : 2,
      "barValueSpacing" : 5,
      "barDatasetSpacing" : 1,
      "responsive": true,
      "maintainAspectRatio": false
  }
}

The json above combined with:

{{ % barchart name="chart" url="path/to/data.json" includejs="true" %}}

Provides a basic chart giving the perfomance diffrence between hugo 0.11 and a few other static site generators:

As a final note the “includejs” variable is there skip including the same static resources if multiple charts is displayed on the same page.

Galleries

Creating galleries have proven to be a bit more complex than generating graphs, but I believe that I’ve finally found a way to make the process close to streamlined. I’ve manged to get it down to three steps (not including taking the photos)

  1. Export from lightroom (or any other source of image)
  2. Run python script to generate thumbs, images for small screens and regular images as well as a json object containing the relative paths
  3. Run the json object through a short-code on site generation

These steps produces a gallery which looks like this:

I will gloss over the initial step and assume that we have a folder containing the images we wish to use for our gallery. The images does not need to be “prepared” for the web in any way since the helper script will handle compression and scaling for us.

The script itself is a fairly basic python script available here, with a two non standard dependencies, namely Pillow and pyexiv2 which of course is a mere pip install away. The script does three things:

  • Generate thumbnails for the images
  • Scale down images to display size (High-res as well if selected)
  • Generate a descriptive JSON file for the gallery.

A basic call to the script would look something like this:

# Runs script generating both high and low res images
# For more options use --help
$ python Gallery_Generator.py --retina \
  --first "mybigimage.jpg" /path/to/my/images

This would create a folder with both thumbnails and scaled-down images, it would also create a bigger thumbnail for the image specified in the script call. If no image is specified it will use the first one as a cover image for the gallery.

To add the gallery to a post we will need a short-code similar to the one used for the charts

{{ % gallery  name="demo" url="path/to/gallery.json" %}}

All the short-codes and scripts described above is available here and they should be fairly easy to add to your own project.