Using Unsplash for Featured Images in Jekyll

Unsplash is the Internet’s most popular source of royalty-free images, and offers both unlimited public downloads as well as private API-based usage.

If you open a link to any Unsplash photo, the URL takes the following format:

https://unsplash.com/photos/9wYdW55NbnY

If you click on the Download button, the URL for that operation matches the following:

https://unsplash.com/photos/9wYdW55NbnY/download?force=true

Where 9wYdW55NbnY is the ID of the photo.

If the ?force=true query string is removed, the photo is loaded within the browser rather than being downloaded to disk.

It’s also possible to add other query string to the URL in keeping with Unsplash’s API. One of those strings affects the size of the photo that’s displayed. An example would look like this:

https://unsplash.com/photos/9wYdW55NbnY/download?w=1000

Where the photo’s width is specified as 1000px.

This URL structure for directly linking to any Unsplash photo (via it’s unique ID) is what we’ll be using to populate the OpenGraph featured image that’s shown when a link is shared via social media, instant messaging, etc.

Front Matter Configuration

Each page in Jekyll has it’s configuration set by YAML front matter. A common configuration looks like this:

layout: post
title: "Using Unsplash for Featured Images in Jekyll"
excerpt: "Programmatically use Unsplash for OpenGraph image URLs in blog posts and site pages."
date: 2021-05-18

The above is actually the front matter for this very blog post. In this configuration block, we can then insert the Unsplash image ID as a key-value pair:

unsplash: "9wYdW55NbnY"

Now, we can reference that ID as a variable in Jekyll using the syntax {{ page.unsplash }} when working with our site’s SEO templating as we’ll see in the next section.

SEO Syntax

Now that the variable for the image resides in the page’s front matter, we can use it within standard OpenGraph markup in the following manner:

<meta property="og:image" content="https://unsplash.com/photos/{{ page.unsplash }}/download?w=1000">
<meta name="twitter:image" content="https://unsplash.com/photos/{{ page.unsplash }}/download?w=1000">

The above (combined with other SEO tags) should be placed in the head.html in your Jekyll _includes directory, or in whatever custom template partial that you utilize for configuring SEO on every page.

Once the unsplash key is present in the page’s front matter, the above URLs will resolve and load the specified Unsplash image.

Of note, 1000px strikes a good balance between the size and quality requirements for a featured image.

You can change the width value to whatever you want, but keep in mind that apart from the performance hit you’ll also place undue burden on the (free) Unsplash service if you request a larger-resolution image.

Front Matter Defaults

It’s now easy to browse Unsplash for images, copy the image ID, and then insert it into any page’s front matter.

However, for existing pages that have not yet been customized with a specific image ID, it’s a good idea to set global front matter defaults so that at least a generic image is shown.

In your Jekyll project’s _config.yml file, add the following block to enable the unsplash front matter key with a default Unsplash image ID of your choosing.

This value will be used if the page doesn’t have it’s own Unsplash ID (the page’s key-value pair will override the global setting):

defaults:
  -
    scope:
      path: "" # an empty string here means all files in the project
      type: "pages"
    values:
      unsplash: "M8FzmNMBYek"
  -
    scope:
      path: ""
      type: "posts"
    values:
      unsplash: "7W3X1dAuKqg"

Testing

After running the usual bundle exec jekyll serve command to start a local server, you can inspect the source of any page and you the Unsplash image should be displayed in your OpenGraph markup.

For example, the displayed feature image for this blog post is:

<meta property="og:image" content="https://unsplash.com/photos/9wYdW55NbnY/download?w=1000">
<meta name="twitter:image" content="https://unsplash.com/photos/9wYdW55NbnY/download?w=1000">

You can now build and deploy your Jekyll website.

Once it’s live you can share a URL via Telegram, Twitter, etc. and the Unsplash featured image should display as expected.

18 May 2021 guides