Adding Descriptions to Pages with Jekyll

What is a page description and how to add one with Jekyll

I have been testing out an SEO tool called Scrutiny5 recently (review coming soon) and as part of my test I wanted to run some scans on this very site. I figured with only 5 pages I would get some good quick feedback.

One of the things that was highlighted immediately to me was that my desciptions were identical for each page.

The description is a bit of meta data associated with a web page that will get shown in places like search results pages.

As amazing as my default description is, it isn’t very helpful.

Jekyll and Front Matter

When compiling your static website Jekyll looks for blocks of Front Matter at the start of your file, these are YAML instructions.

The most basic you can get away with would be something like;

layout: post

Adding a description with Jekyll

To add a description you simply add the following in your front matter;

layout: post
description: This is my awesome writeup of this fantastic thing

You can do this on any type of page, it isn’t restricted to posts.

Making sure your description is seen

You will want to make sure your layout files are looking for the correct description, here is what mine looks like;

    <meta name="description" content="{% if page.description %}{{ page.description }}{% else %}{{ site.description }}{% endif %}">

Jekyll Default

If you don’t use a specific description as I have just shown you then Jekyll will fall back to using the site.description, this is something you can set in your _config.yml file and again it will look just like it does when included in Front Matter.


If you have any questions about the use or implementation of this please let me know in the comments.

Recent posts View all


Iterate over indexed params in Rails

When your API isn't Rails-shaped, sometimes you need to handle input differently

Web Dev Jekyll

Running Jekyll from inside VS Code

How to set up your VS Code to run Jekyll without needing extra extensions