Jekyll Permalinks

Introduction

Jekyll is a static-site generator that provides some of the powerful templating functions of a database driven Content Management System (CMS). Jekyll is well-suited for people looking for a lightweight solution without the hassle of webforms and post requests.

This tutorial’s focus is on how Jekyll handles URLs. You know, the thing people rely on to navigate your website.

We’ll look at how Jekyll creates URLs, and how to change those URL patterns using what are known as permalinks.

File Structure

The _site directory contains the static site that is served to the client. Like most static websites Jekyll’s directory structure on disk maps directly to the URLs used by the client. By default Jekyll will transform post categories into directories and explode the date into the file structure. This means the final URL pattern for the post will become /category1/category2/YYYY/MM/DD/words-in-title.html. This becomes a literal URL path such as: http://localhost:4000/jekyll/update/2022/04/30/welcome-to-jekyll.html.

Below is an example of a simple Jekyll directory structure.

Default File Tree

.
├── 404.html
├── about.md
├── assets
│   └── postcard.jpg
├── _config.yml
├── Gemfile
├── Gemfile.lock
├── index.md
├── _posts
│   └── 2022-04-30-welcome-to-jekyll.markdown
└── _site
   ├── 404.html
   ├── about
   │   └── index.html
   ├── assets
   │   ├── main.css
   │   └── postcard.jpg
   ├── feed.xml
   ├── index.html
   └── jekyll
        └── update
           └── 2022
                └── 04
                    └── 30
                        └── welcome-to-jekyll.html

URL Creation

Jekyll’s URL creation is both flexible and powerful. The URLs can be determined by where and how you store the source files, and it can be dynamically overridden with a specific value or permalink pattern.

Page Defaults

Pages in Jekyll are created by creating a file and/or directory in the root structure of your Jekyll deployment. For example, contact.md would become http://localhost:4000/contact.html. If it was placed in one or more subdirectories, those would also become a part of the URL path. This means placing contact.md in a directory called main would create an URL like http://localhost:4000/main/contact.html.

Post Defaults

Posts are a bit different than pages in Jekyll. First and foremost posts are saved under the _post directory in your Jekyll deployment root. Posts added to the directory have the following naming syntax YEAR-MONTH-DAY-title.MARKUP where YEAR is a four-digit number, MONTH and DAY are both two-digit numbers, and MARKUP is the file extension representing the format used in the file.

The default post pattern is /:categories/:year/:month/:day/:title:output_ext. This pattern is based on the post’s file name and/or front matter values. The front matter values that affect the directory structure are: date:, title:, and categories:. The value for categories must be set in the post front matter, however the other two are optional. If date: and title: are not set then the url will be built using the filename.

title: Sample
categories: Jekyll Tutorials Examples
date: 2022-04-30 10:55:00 +0000

About Permalinks

Permalinks are a powerful yet flexible tool in Jekyll for building our site URLs. Permalinks allows us to make changes to the URLs without adding directory after directory after directory to our root directory. In essence it helps keep our workspace as programmers clean and organized, without having to worry about how it looks to our users.

For example if we make a file in our root directory called about.md it’s URL would be http://localhost:4000/about.html. But most people would prefer their URL to look something like http://localhost:4000/about/. Notice the lack of a file extension? Without permalinks doing this would require creating a directory in a root directory called about and then placing in the about directory a file called index.md. But with permalinks it can be as simple as placing this in the front matter of our about.md file:

permalink: /about/

File Specific Permalinks

Like the example above, these permalinks are placed in the front matter of each individual markdown file. The permalinks set at the webpage level must be a static value.

Global Permalinks

Another way to configure permalinks is to create global permalinks. Global permalinks are placed in the _config.yml file located in our root directory.

This is Jekyll’s default value:

permalink: /:categories/:year/:month/:day/:title:output_ext

For pages that don’t have some of the aspects defined, such as categories or time, the missing aspects are ignored. For example, the default permalink style will become /:title:output_ext for pages and collections.

Permalink Placeholders

Permalink Built-in Formats

Collections

For collections, you have the option to override the global permalink in the collection configuration in _config.yml:

collections:
  my_collection:
    output: true
    permalink: /:collection/:name