Edit this page on Github

Permalinks of items can be customized with a template through the config.yml file of your site or as an attribute for each page. Permlinks let's specify where compiled items should be written.

permalink: "/:path/:basename.:extension"

Template variables

Name Description
:path Relative path to content folder without filename. e.g: posts.
:extension Filename extension. e.g: md.
:basename Base name of the file without path info. e.g: /about/changelog.md gets changelog.
:collection Collection name assigned to an item. e.g: posts.
:categories The categories from the post.
:title Title from the post. Slugified tittle. e.g: welcome-to-my-blog.
:year Year extracted from date attribute or current date. e.g: 2015.
:month Month extracted from date attribute or current date. e.g: 01.
:i_month Month extracted from date attribute or current date without leading zeros. e.g: 1.
:day Day extracted from date attribute or current date. e.g: 01.
:i_day Day extracted from date attribute or current date without leading zeros. e.g: 1.

Predefined permalink templates

Spress have a few predefined permalink templates. If you want to configure it on your site simply use its name:

Name Template Example
none /:path/:basename.:extension /about/changelog.html
pretty /:categories/:year/:month/:day/:title or /:path/:basename. /news/2015/12/31/new-apps/
ordinal /:categories/:year/:i_day/:title.:extension /news/2015/31/new-apps.html
date /:categories/:year/:month/:day/:title.:extension /2015/12/31/new-apps.html

The default value of permalink attribute is pretty. All predefined permalink templates with a date component depends of date attribute. In case of missing, none template will be applied.

The pretty style

This is a "extensionless" permalink that contain neither a trailing slash nor a file extension. If the out extension of an item is other than html then none template will be applied. Sometimes this configuration requires additional support from the web server. See try_files on Nginx or multiviews on Apache.

Forcing the "extensionless" mode with custom permalinks

Spress >= 2.1.0 In case of you want to force the extensionless mode from pretty style with the custom pernalink of an item, you can add this attribute at the front matter block: no_html_extension: true.

For example: an item with path content/foo.html and permalink attribute: amazing-foo will generate a page with a path: build/amazing-foo which has /amazing-foo as relative URL. If you set no_html_extension to true, the result will be a page with a path: build/amazing-foo/index.html which has amazing-foo as relative URL.

To enable this feature globally, set no_html_extension to true in the config.yml file.