Improve this page

Permalinks

Jekyll supports a flexible way to build your site’s URLs. You can specify the permalinks for your site through the Configuration or in the YAML Front Matter for each post. You’re free to choose one of the built-in styles to create your links or craft your own. The default style is date.

Permalinks are constructed by creating a template URL where dynamic elements are represented by colon-prefixed keywords. For example, the default date permalink is defined according to the format /:categories/:year/:month/:day/:title.html.

Template variables

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 filename. (00..23)
minute	Minute of the hour from the Post’s filename. (00..59)
second	Second of the minute from the Post’s filename. (00..60)
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.

Built-in permalink styles

While you can specify a custom permalink style 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

Pages and collections

The permalink configuration setting specifies the permalink style used for posts. Pages and collections each have their own default permalink style; the default style for pages is /:path/:basename and the default for collections is /:collection/:path.

These styles are modified to match the suffix style specified in the post permalink setting. For example, a permalink style of pretty, which contains a trailing slash, will update page permalinks to also contain a trailing slash: /:path/:basename/. A permalink style of date, which contains a trailing file extension, will update page permalinks to also contain a file extension: /:path/:basename:output_ext. The same is true for any custom permalink style.

The permalink for an individual page or collection document can always be overridden in the YAML Front Matter for the page or document. Additionally, permalinks for a given collection can be customized in the collections configuration.

Permalink style examples

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 for details.	/2009/04/slap-chop

Extensionless permalinks

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 extensionless 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 very 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;

Back

Next