Permalinks

A permalink is simply the determination of what the output URL of your resource will be. Every resource uses a permalink processer to figure out where to save your transformed resource in the output folder tree.

Resources in the pages collection are the most straightforward. The filenames and folder structure of your pages will result in matching output URLs. For example, a file saved at src/_pages/this/is/great.md would be output to /this/is/great/.

For resources in the posts collection, Bridgetown ships with few permalink “styles”. The posts permalink style is configured by using the permalink key in the config file. If the key isn’t present, the default is pretty.

The available styles are:

pretty: /[locale]/:categories/:year/:month/:day/:slug/
pretty_ext: /[locale]/:categories/:year/:month/:day/:slug.*
simple: /[locale]/:categories/:slug/
simple_ext: [locale]/:categories/:slug.*

(Including .* at the end simply means it will output the resource with its own slug and extension. Alternatively, / at the end will put the resource in a folder of that slug with index.html inside.)

To set a permalink style or template for a custom collection, add it to your collection metadata in bridgetown.config.yml. For example:

collections:
  articles:
    permalink: pretty

would make your articles collection behave the same as posts. Or you can create your own template:

collections:
  articles:
    permalink: /lots-of/:collection/:year/:title/

This would result in URLs such as /lots-of/articles/2021/super-neato/.

Placeholders #

All of the segments you see above starting with a colon, such as :year or :slug, are called placeholders. Bridgetown ships with a number of placeholders, but you can also create your own! See the placeholders plugin page for details.

Here’s the full list of built-in placeholders available:

Variable	Description
`:year`	Four-digit year based on the resource's date.
`:short_year`	Two-digit year based on the resource's date within its century (00..99).
`:month`	Month based on the resource's date (01..12).
`:i_month`	Month based on the resource's date without leading zeros (1..12).
`:day`	Day of the month based on the resource's date (01..31).
`:i_day`	Day of the month based on the resource's date without leading zeros (1..31).
`:categories`	The specified categories for the resource. If a resource has multiple categories, Bridgetown will create a hierarchy (e.g. `/category1/category2`). Bridgetown automatically parses out double slashes in the URLs, so if no categories are present, it will ignore this.
`:locale`, `:lang`	Adds the locale key of the current rendering context, if its not the default site locale.
`:title`	Title from the resource's front matter (aka `title: My Resource Title`), slugified (aka any character except numbers and letters is replaced as hyphen).
`:slug`	Extracted from the resources’s filename. May be overridden via the resources’s `slug` front matter.
`:name`	Extracted from the resources’s filename and cannot be overridden.
`:path`	Constructs URL segments out of the relative path of the resource within its collection folder. Used by the pages collection as well as custom collections if no specific permalink config is provided.
`:collection`	Outputs the label of the resource's custom collection (will be blank for the built-in pages and posts collections).

Back to Resources