front matter

Introduction

Permalinks are a flexible way to build site urls. We might want to have a particular file structure for build the site then change it for the live site. Permalinks allow us to do this.

We have a /blog.html page and want the URL on the live site to be /blog/. One way we could do this is create a new folder called blog, move blog.html in that folder and then rename it to index.html. The problem with this is we’re creating folders just to have the URLs we want. Let’s move /blog/index.html back to /blog.html and solve this with permalinks. We can add a permalink in front matter, then we just need to specify the URL we want:

---
layout: default
title: Blog
permalink: /blog/
---
...

Going to blog.html in the browser 404s whereas /blog/ now outputs the blog page.

Blog post permalinks

What if we wanted to set a permalink for all our blog posts? We could add a permalink to every blog post but that could take forever. A better way is to set it once for all blog posts in _config.yml. The variables available to us when setting permalinks for posts are as follows:

Variable Description

year

Year from the Post’s filename.

month

Month from the Post’s filename.

i_month

Month from the Post’s filename without leading zeros.

day

Day from the Post’s filename.

i_day

Day from the Post’s filename without leading zeros.

short_year

Year from the Post’s filename without the century.

hour

Hour of the day, 24-hour clock, zero-padded from the post’s date front matter. (00..23)

minute

Minute of the hour from the post’s date front matter. (00..59)

second

Second of the minute from the post’s date front matter. (00..59)

title

Title from the document’s filename. May be overridden via the document’s slug YAML front matter.

slug

Slugified title from the document’s filename (any character except numbers and letters is replaced as hyphen). May be overridden via the document’s slug YAML front matter.

categories

The specified categories for this Post. If a post has multiple categories, Jekyll will create a hierarchy (e.g. /category1/category2). Also Jekyll automatically parses out double slashes in the URLs, so if no categories are present, it will ignore this.

Let’s make the permalink the day, then the month, then the year followed by the title of the post.

...
permalink: /:day/:month/:year/:title/
...

The permalink variables available to collections are as follows:

Variable Description

collection

Label of the containing collection.

path

Path to the document relative to the collection's directory.

name

The document's base filename, with every sequence of spaces and non-alphanumeric characters replaced by a hyphen.

title

The document's lowercase title (as defined in its front matter), with every sequence of spaces and non-alphanumeric characters replaced by a hyphen. If the document does not define a title in its front matter, this is equivalent to name.

output_ext

Extension of the output file.

We can add a permalink to metadata of the collection in _config.yml:

collections:
  cookies:
    output: true
    permalink: /baked-goods/:path/
...

Instead of linking to /cookies/afghan/ we would now link to /baked-goods/afghan/.