Routes

Route requests.

If you ever need to map a URL to a simple template/layout view, you can do so without having to add a placeholder content file by using a routes file, _config/routes.yaml. Custom routed URLs will always override content URLs if there is a duplicate, so keep that in mind. Note the prefixed slash, it’s important.

# Visiting example.com/success will...
# load the /templates/success.html template with the default layout

/success: success

A more complex example:

# Visiting example.com/members/login will...
# load the /templates/success.html template and use the 'system' layout

/members/login:
  template: success
  layout: system

Ignoring Segments

You can also add a list of segments that should be ignored if found in your URLs. For example, if you want to ignore any segments that are “gallery” or “details,” you can do so like this:

# ignore these segments
ignore:
  - gallery
  - details

These values will still appear in your {{ segment_n }} variables, but will not factor into figuring out which content to render. This could be helpful if you have a second page with many sub-pages, but want to control them all from the one main page. You can ignore segments in the URL, but check of their presence in your template.

Continuing the above example, you could still check for the following:

{{ if segment_3 == "gallery" }}
    {{# show the gallery #}}
{{ else }}
    {{# show the overview page #}}
{{ endif }}

Wildcard Routes Added in v1.7

Wildcard routes let you capture multiple routes at one time. You can use wildcards anywhere in your route pattern, and you can use multiple wildcards per route. There are two types of wildcards that you can use: standard wildcards and (as of v1.8.4) named wildcards.

Standard Wildcards

A standard wildcard replaces the segment you wish to wildcard with a *. For example:

# before
routes:
  /blog/categories/purple: purple-template
  /blog/tags/purple: purple-template

# after
routes:
  /blog/*/purple: purple-template

Any URL with blog as the first segment, anything for the second segment, and purple for the third segment will trigger this route.

Named Wildcards Added in v1.8.4

A named wildcard replaces the segment you wish to wildcard with a name surrounded with {}. For example:

# before
routes:
  /blog/categories/purple: purple-template
  /blog/tags/purple: purple-template

# after
routes:
  /blog/{type}/purple: purple-template

In this example, instead of using *, we’re using {type}. In your template (which, for this example, will be purple-template), the {{ type }} variable becomes available with the value of whatever was in the second segment. Named routes can use upper and lowercase letters, numbers, and underscores.

Mix’em Up

You can use standard and named wildcards together in one route. For example:

# before
routes:
  /blog/categories/purple: purple-template
  /blog/tags/purple: purple-template
  /calendar/categories/purple: purple-template
  /calendar/tags/purple: purple-template

# after
routes:
  /*/{type}/purple: purple-template

In this example, any URL with anything as the first segment, anything as the second segment, and purple as the third segment will trigger this route, and {{ type }}’s value will be whatever is in the second segment.