Routes

Table of contents

• Defining Routes
• Aliasing Routes
• Configuring Routes
• Example Routes
• The route() function

Defining routes

Routes are defined in the page frontmatter using the route property.

----
route:  /the-page-route
---

Note: If the route property is not defined, the default route will be set to the absolute path of the page.

Aliasing routes

Multiple routes can be defined for the same page. The first route is considered as the canonical route and is used to create the canonical URL for the page.

route:
   - /page/route
   - /my-page-alias

Note: If multiple routes are defined and you wish to include the absolute page route, you need to manually add it again. If you define it first, it will be the canonical route.

Configuring routes

Wildcards let you capture multiple routes at once. Wildcards are available anywhere in your route and there aren’t any limits to how many you can use.

Wildcards need to be placed between [...] and can contain a named parameter prefixed by a constraint.

Example: /users/[digit:id]

Wildcards can be made optional by appending them with a ?.

Example: /users/[digit:id]?

Wildcards

For example can use the following wildcards in your routes.

- [digit]              // Match numeric characters
- [alnum:id]           // Match alphanumeric characters as 'id'
- [alpha:action]       // Match alphabetic characters as 'action'
- [:action]            // Match anything up to the next / or end of the URI as 'action'
- [create|edit:action] // Match either 'create' or 'edit' as 'action'
- [*]                  // Catch all (lazy, stops at the next trailing slash)
- [*:trailing]         // Catch all as 'trailing' (lazy, stops at the next trailing slash)
- [**:trailing]        // Catch all (possessive - will match the rest of the URI)
- .[:format]?          // Match an optional parameter 'format' - a / or . before the block is also optional

The character before the colon (the 'constraint') is a shortcut for one of the following regular expressions:

'digit' => '[0-9]++'       //numeric
'alnum' => '[0-9A-Za-z]++' //alphanumeric 
'alpha' => '[A-Za-z]++',   //alphabetic 
'*' => '.+?'
'**' => '.++'
'' => '[^/.]++'

Example routes

Show the same page for English, French and German

route: 
   - /en/the-page-route
   - /fr/the-page-route
   - /de/the-page-route

or

route: /[en|fr|de]/the-page-route

The route() function

If you want to generate an URL for a page you can use the route($page, $query = array(), $escape = false) template function. The function accepts three parameters:

• $page: A page path, or page object
• $query: Additional query parameters used to generate the URL
• $escape: If true, the URL will be escaped, for example for use in javascript.

Fragments that are included in the path are also appended to the resulting URL.

Example:

$url = route('path/to/page#fragment');

or

$url = route(page()#fragment);