Permalinks

Permalinks refer to the URLs (excluding the domain name or directory folder) for your pages, posts, or collections. Jekyll supports a flexible way to build permalinks, allowing you to leverage various template variables or choose built-in permalink styles (such as date) that automatically use a template-variable pattern.

You construct permalinks by creating a template URL where dynamic elements are represented by colon-prefixed keywords. The default template permalink is /:categories/:year/:month/:day/:title.html. Each of the colon-prefixed keywords is a template variable.

You can configure your site’s permalinks through the Configuration file or in the Front Matter for each post, page, or collection.

Setting permalink styles in your configuration file applies the setting globally in your project. You configure permalinks in your _config.yml file like this:

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

If you don’t specify any permalink setting, Jekyll uses the above pattern as the default.

The permalink can also be set using a built-in permalink style:

permalink: date

date is the same as :categories/:year/:month/:day/:title.html, the default. See Built-in Permalink Styles below for more options.

Setting the permalink in your post, page, or collection’s front matter overrides any global settings. Here’s an example:

---
title: My page title
permalink: /mypageurl/
---

Even if your configuration file specifies the date style, the URL for this page would be http://somedomain.com/mypageurl/.

When you use permalinks that omit the .html file extension (called “pretty URLs”) Jekyll builds the file as index.html placed inside a folder with the page’s name. For example:

├── mypageurl
│   └── index.html

With a URL such as /mypageurl/, servers automatically load the index.html file inside the folder, so users can simply navigate to http://somedomain.com/mypageurl/ to get to mypageurl/index.html.

Template variables for permalinks

The following table lists the template variables available for permalinks. You can use these variables in the permalink property in your config file.

Variable Description

year

Year from the post's filename. May be overridden via the document’s date YAML front matter

month

Month from the post's filename. May be overridden via the document’s date YAML front matter

i_month

Month without leading zeros from the post's filename. May be overridden via the document’s date YAML front matter

day

Day from the post's filename. May be overridden via the document’s date YAML front matter

i_day

Day without leading zeros from the post's filename. May be overridden via the document’s date YAML front matter

short_year

Year without the century from the post's filename. May be overridden via the document’s date YAML 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 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.

Note that all template variables relating to time or categories are available to posts only.

Built-in permalink styles

Although you can specify a custom permalink pattern using template variables, Jekyll also provides the following built-in styles for convenience.

Permalink Style URL Template

date

/:categories/:year/:month/:day/:title.html

pretty

/:categories/:year/:month/:day/:title/

ordinal

/:categories/:year/:y_day/:title.html

none

/:categories/:title.html

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

Specifying permalinks through the YAML Front Matter

Built-in permalink styles are not recognized in YAML Front Matter. As a result, permalink: pretty will not work.

Here are a few examples to clarify how permalink styles get applied with posts.

Given a post named: /2009-04-29-slap-chop.md

URL Template Resulting Permalink URL

None specified, or permalink: date

/2009/04/29/slap-chop.html

pretty

/2009/04/29/slap-chop/

/:month-:day-:year/:title.html

/04-29-2009/slap-chop.html

/blog/:year/:month/:day/:title/

/blog/2009/04/29/slap-chop/

/:year/:month/:title

See Extensionless permalinks with no trailing slashes for details.

/2009/04/slap-chop

Permalink settings for pages and collections

The permalink setting in your configuration file specifies the permalink style used for posts, pages, and collections. However, because pages and collections don’t have time or categories, these aspects of the permalink style are ignored with pages and collections.

For example:

  • A permalink style of /:categories/:year/:month/:day/:title.html for posts becomes /:title.html for pages and collections.
  • A permalink style of pretty (or /:categories/:year/:month/:day/:title/), which omits the file extension and contains a trailing slash, will update page and collection permalinks to also omit the file extension and contain a trailing slash: /:title/.
  • A permalink style of date, which contains a trailing file extension, will update page permalinks to also contain a trailing file extension: /:title.html. But no time or category information will be included.

The path to the post or page in the built site differs for posts, pages, and collections:

Posts

The subfolders into which you may have organized your posts inside the _posts directory will not be part of the permalink.

If you use a permalink style that omits the .html file extension, each post is rendered as an index.html file inside a folder with the post’s name (for example, categoryname/2016/12/01/mypostname/index.html).

Pages

Unlike posts, pages by default mimic the source directory structure exactly. (The only exception is if your page has a permalink declared its front matter — in that case, the structure honors the permalink setting instead of the source folder structure.)

As with posts, if you use a permalink style that omits the .html file extension, each page is rendered as an index.html file inserted inside a folder with the page’s name (for example, mypage/index.html).

Collections

By default, collections follow a similar structure in the _site folder as pages, except that the path is prefaced by the collection name. For example: collectionname/mypage.html. For permalink settings that omit the file extension, the path would be collection_name/mypage/index.html.

Collections have their own way of setting permalinks. Additionally, collections have unique template variables available available (such as path and output_ext). See the Configuring permalinks for collections in Collections for more information.

Flattening pages in _site on build

If you want to flatten your pages (pull them out of subfolders) in the _site directory when your site builds (similar to posts), add the permalink property to the front matter of each page, with no path specified:

---
title: My page
permalink: mypageurl.html
---

Jekyll supports permalinks that contain neither a trailing slash nor a file extension, but this requires additional support from the web server to properly serve. When using these types of permalinks, output files written to disk will still have the proper file extension (typically .html), so the web server must be able to map requests without file extensions to these files.

Both GitHub Pages and the Jekyll’s built-in WEBrick server handle these requests properly without any additional work.

Apache

The Apache web server has extensive support for content negotiation and can handle extensionless URLs by setting the multiviews option in your httpd.conf or .htaccess file:

Options +MultiViews

Nginx

The try_files directive allows you to specify a list of files to search for to process a request. The following configuration will instruct nginx to search for a file with an .html extension if an exact match for the requested URI is not found.

try_files $uri $uri.html $uri/ =404;

You can create links in your topics to other posts, pages, or collection items in a way that is valid no matter what permalink configuration you choose. By using the link tag, if you change your permalinks, your links won’t break. See Linking to pages in Templates for more details.