GreenHat SBS images

GreenHat SBS does a lot of image processing to make your life easier. It will, for example, create multiple images of different sizes to support the various platforms (desktop, tablet and phone). You don’t want to be inflicting large images on phone users.

What image sizes does it generate?

You can tell it what sizes to generate in your _config.yaml file via the imageSizes setting. By default it is as follows:

imageSizes: [320, 768, 1024, 1600, 1920]

Creating images

Create the largest image you think you’ll need using one of the sizes from the above setting.

Name the image correctly. It must end with -nnnnw where nnnn is the size. So if I wanted a picture of my cat, I would create a file called:

my-cat-1920w.jpg

Note the 1920w at the end of the file name, just before the extension. This image would 1920 pixels wide.

SBS will then take that image and create copies in all the different sizes (only those smaller than the image you created) specified in the imageSizes option (see above). So if you were using the sizes in the above example it would create:

my-cat-320w.jpg
my-cat-768w.jpg 
my-cat-1024w.jpg 
my-cat-1600w.jpg

And of course you’ve already created:

my-cat-1920w.jpg

It caches these images and will only update the cache if you add or alter an image.

None of this implies you must use multiple-sized images. SBS will only attempt to resize images that end with -nnnnw and if you don’t end an image file name with that, it will just treat it as a normal image and not create multiple sizes.

The rest of this article applies whether you use resizable images or not.

Using images

You use images in a post by first adding them to the front matter and then tagging them in the post where you want them to appear.

Article front matter

Here are all the possible settings you could use for an image in an article’s front matter (using my example cat image from above):

images:
    cat-image: 
        url: /assets/posts/my-cat-1920w.png
        alt: A picture of my cat.
        caption: My cat asleep on the settee.
        credit: Gordy's Discourse.
        copyright: Gordon Ansell, 2020.
        iconImage: true
        summaryImage: true
        featuredImage: true
        sizes: 33vw
        class: s33 left
        link: http://somewhere.com
        title: Just a cat picture

In most cases you don’t need to use all those settings but I’ll define them here in case you need them.

cat-imageThis is the ‘tag’ for the image and how you’ll refer to it in the body of the post. All images should have a tag underneath (and indented from) the main ‘images’ tag.
urlThis is the the relative URL to the image. The assets directory is where images should be, although you can put it in any subdirectory underneath that. I mentioned how SBS creates various image sizes for you — you don’t need to specify them all here, just use the URL for your original image. Note that it’s a relative URL (no domain name) and it begins with a forward slash.
altThis is the HTML ‘alt’ for the image. All images should have an ‘alt’ but if you don’t specify one it will use the ‘caption’ if you have specified that.
caption(optional) If you want a caption to appear underneath your image, specify it here.
credit(optional) If you want to credit someone for the image, specify it here.
copyright(optional) If you want to indicate a copyright for the image, specify it here.
iconImage(optional) If you want to use this image as an icon next to the article excerpt on the home page, give iconImage a true value (it’s false by default)
summaryImage(optional) If you have an article summary and want to use this image to adorn that, give summaryImage a true value (it’s false by default)
featuredImage(optional) A featured image will appear alongside your post when you link to it externally from places like Facebook, Twitter or RSS readers. If you want to indicate which image to use, give this a ‘true’ value. If you don’t specify a featuredImage, SBS will try to find a suitable image from your post to use.
sizes(optional) This tells the browser how big your image is on the page. The 33vw in the example says it will take up 33% of the viewport. If you don’t specify sizes but do specify a class (which I recommend), it will derive the sizes statement from the class if it can.
class(optional) This is the CSS class you wish to add to the image. A special class ‘sNN’ gives the width of the image on he page, when NN is a number between 1 and 99. So class: s44 would say the image will be 44% wide. You can also say whether to align an image right or left, so class: s65 left says you want an image that’s 65% wide and aligned to the left. If you specify nothing for both class and sizes the image will be 100% wide.
link(optional) Use this if you want your image to link to somewhere. By default it will just open the largest version of your image in a browser window.
title(optional) This is the HTML title of the image.

That’s quite a lot of settings but you usually don’t need most of them. If I just wanted my cat image, taking up 50% of the width and aligned to the right, I may use something like this:

images:
    cat-image: 
        url: /assets/posts/my-cat-1920w.png
        alt: A picture of my cat.
        class: s50 right

Article body

Once you’ve defined an image, just include it in the article body where you want it to appear as follows:

(((image-tag)))

Where the ‘tag’ is the image tag from the front matter. So for the example image of my cat I’ve been using, it would be:

(((image-cat-image)))