Rubyists Assemble! We're currently raising funds to help drive the launch of 1.0! Join the effort today ▸

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! Simply use the register_placeholder in a plugin, perhaps at the bottom of your plugins/site_builder.rb file. For example, if you wanted a placeholder to resolve a resource data, you could add:

Bridgetown::Resource::PermalinkProcessor.register_placeholder :ymd, ->(resource) do
  "#{resource.date.strftime("%Y")}#{resource.date.strftime("%m")}#{resource.date.strftime("%d")}"
end

Bridgetown::Resource::PermalinkProcessor.register_placeholder :y_m_d, ->(resource) do
  "#{resource.date.strftime("%Y")}-#{resource.date.strftime("%m")}-#{resource.date.strftime("%d")}"
end

Thus with a permalink key of /blog/:ymd/:slug/, you’d get /blog/20211020/my-post/, or for /blog/:y_m_d/:slug/ you’d get /blog/2021-10-20/my-post/.

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 mattter (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 Structure