Jekyll Permalinks

Episode #12 - Apr 28, 2016 - 6 minutes

Subscribe to Jekyll Casts

Permalinks are a flexible way to build your site urls. We might want to have a particular file structure for managing our Jekyll site and then completely change the file structure for the live site. Permalinks allow us to do this. We have a /blog.html page and let’s say we want the URL for this 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 and going to /blog/ outputs the blog page. So that’s an example of setting the permalink on individual pages but what if we wanted to set a permalink for all our blog posts. We could add this permalink to every blog post or 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/
...

In this final example we’ll do the same thing for our cookies collection. 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’re linking to /baked-goods/afghan/

Subscribe to Jekyll Casts