Improve this page

Permalinks

Permalinks are the output path for your pages, posts, or collections. They allow you to structure the directories of your source code different from the directories in your output.

Front MatterPermalink

The simplest way to set a permalink is using front matter. You set the permalink variable in front matter to the output path you’d like.

For example, you might have a page on your site located at /my_pages/about-me.html and you want the output url to be /about/. In front matter the page you would set:

---
permalink: /about/
---

GlobalPermalink

Setting a permalink in front matter for every page on your site is no fun. Luckily, Jekyll let’s you set in globally in your _config.yml.

To set a global permalink, you use the permalink variable in _config.yml. You can use placeholders to your desired output. For example:

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

Note that pages and collections don’t have time or categories, these aspects of the permalink style are ignored for the output.

For example, a permalink style of /:categories/:year/:month/:day/:title:output_ext for posts becomes /:title.html for pages and collections.

PlaceholdersPermalink

Here’s the full list of placeholders available:

Variable	Description
year	Year from the post's filename. May be overridden via the document’s date front matter
month	Month from the post's filename. May be overridden via the document’s date front matter
i_month	Month without leading zeros from the post's filename. May be overridden via the document’s date front matter
day	Day from the post's filename. May be overridden via the document’s date front matter
i_day	Day without leading zeros from the post's filename. May be overridden via the document’s date front matter
y_day	Day of the year from the post's filename, with leading zeros.
short_year	Year without the century from the post's filename. May be overridden via the document’s date front matter
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 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 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.

Built-in formatsPermalink

For posts, Jekyll also provides the following built-in styles for convenience:

Permalink Style	URL Template
date	/:categories/:year/:month/:day/:title:output_ext
pretty	/:categories/:year/:month/:day/:title/
ordinal	/:categories/:year/:y_day/:title:output_ext
none	/:categories/:title:output_ext

Rather than typing permalink: /:categories/:year/:month/:day/:title/, you can just type permalink: pretty.

Specifying permalinks through the front matter

Built-in permalink styles are not recognized in front matter. As a result, permalink: pretty will not work.

CollectionsPermalink

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

Collections have the following placeholders available:

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 :title template variable will take the slug front matter variable value if any is present in the document; if none is defined then :title will be equivalent to :name, aka the slug generated from the filename.
:output_ext	Extension of the output file. (Included by default and usually unnecessary.)