How to Create a Featured Image Template for a Jekyll Blog Site

camera on a stand pointing toward a mountain

I wanted to share a solution I came up with for displaying a blog post’s Featured Image on a Jekyll site.  There are two primary places I want to display this image:

  1. The page containing the blog post (post page)
  2. Within a loop of blog posts on any number of pages (i.e., home page, blog archives page)

We will create a template file in the _includes directory to display an HTML img element.  The image’s src and alt attributes will be a variable in the post’s Front Matter.  And we’ll only load this template file if the post has a variable for the featured image.  Let’s start with the post-featured-image.html template file, located in the project’s _includes directory:

<img class="feat-img" src="{{ site.baseurl }}/assets/images/{{ include.image }}" alt="{{ include.alt | default: 'image representing a theme in this article' }}" />

For my deployment of Jekyll, all images will live in the /assets/image directory.  Depending upon your deployment, you may need to update the src attribute structure.  I’m also using the site.baseurl variable because my project lives in a sub-directory of the main URL.

The two other variables, include.image and include.alt, correspond to variables in the Front Matter of each post.  The reason I’m using include.[variable] instead of page.[variable] or post.[variable] is so that the template file can work on both individual post pages, as well as pages that loop through blog posts.  I’ll review how we call the template file later in this article.  Let me define the purpose of these two featured image variables.

Featured Image Front Matter Variables

  • featured-image: the image file name and extension
  • featured-image-alt: alternative text for the image

As you can see in the template file, I’ve also included a default value for the include.alt variable.  In case the author forgets to define the alternative text, there is a default value.  I agree that there may be a better solution to this.  And if you have one, please leave a comment describing it.

When we call the template file, we must provide a value for the image and alt variables.  If we are calling the template on a post page, we use page.image and page.alt.  If we’re calling it on a page where we are looping through posts, we use post.image and post.alt.

<!-- post.html, located in _layouts directory -->
<!-- other HTML content -->
{% include post-featured-image.html image=page.featured-image alt=page.featured-image-alt %}
<!-- other HTML content -->

When it comes to calling the template file on a page, I wrap it in a conditional statement.  If the featured-image variable (include.image) exists for a post, then I call the template file.  If for some reason a post does not have a featured image, we won’t include the template file.  Again, I don’t want to make assumptions about the structure/content for each post.  There may be a reason why the author chose not to include a featured image.

Now that I’ve described this solution, let me show you how it would be implemented on a Jekyll site.  I’ll include sections of three files in the code snippet below:

  1. Front Matter section of a blog post
  2. A section of the post.html file located in the _layouts directory
  3. A section of page that includes a posts loop

Sample Code

<!– 1. Post File [] –>
layout: post
title: A Sample Post
date: 2018-09-30
author: Mike the Blogger
description: This is the one blog post to rule them all
featured-image: my-awesome-photo.jpg
featured-image-alt: Mike the Blogger speaking at Times Square, New York City, New York
categories: Side Hustle
<!– 2. post.hml; located in the _layouts directory –>
<!– some page content –>
<header class="post-header">
<h1 class="post-title">{{ page.title }}</h1>
<time datetime="{{ | date_to_xmlschema }}">{{ | date: "%b %-d, %Y" }}</time>
{% if %} • {{ }}{% endif %}
<!– call the featured-post-image.html template file –>
{% if page.featured-image %}{% include post-featured-image.html image=page.featured-image alt=page.featured-image-alt %}{% endif %}
<!– other page content –>
<!– 3. index.html, located in project's root directory –>
<!– some HTML content –>
{% for post in site.posts limit:3 %}
<a class="post-link" href="{{ post.url | prepend: site.baseurl }}">{{ post.title }}</a>
<!– call the featured-post-image.html template file –>
{% if post.featured-image %}{% include post-featured-image.html image=post.featured-image alt=post.featured-image-alt %}{% endif %}
<span class="post-meta">{{ | date: "%b %-d, %Y" }}</span>
{% if %} • <span itemprop="author" itemscope itemtype=""><span itemprop="name">{{ }}</span></span>{% endif %}
{% endfor %}
<!– some other HTML content –>


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s