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.

title

Title from the document’s filename. 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.

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

Support for improved page and collection permalinks is currently unreleased.

In order to use this feature, install the latest development version of Jekyll.

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.

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/index.html

/: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

Support for extensionless permalink is currently unreleased.

In order to use this feature, install the latest development version of Jekyll.

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;