Who this is for. The content modeller and the site operator who need a record to answer at an address its slug and tree would not give it. Afterwards you can choose between a custom URL and a redirect, and predict which address a link will use.
What a custom URL is
A custom URL is a path, such as /summer-sale, attached to one record. It is set in the record's Custom Url field in the admin, or through the API (Custom URLs and slugs). These records can carry one: pages, books, units and book pages; blogs and blog posts; FAQ pages and questions; custom entity records, when their definition is site-specific; and product and product category descriptions. A custom URL belongs to one site, or to every site of the account when its site is left empty.
How a request finds it
Custom URLs are consulted after rewrites and before the module routes. The request's path is tried whole, then with its last segment removed, and so on, until a custom URL matches. At each length a custom URL of the current site is tried before an account-wide one, and the match ignores case. The matched part of the path is then replaced with the record's own path and the request carries on as if that had been asked for.
One consequence is that a custom URL works as a prefix. A blog whose slug is news, given the custom URL /blog, answers at /blog, and its posts answer at /blog/<post> as well, because /blog/spring-update becomes /blogs/news/spring-update before routing. This site's How-to library is served that way: the blog's custom URL is /how-to and every how-to answers below it.
Both addresses answer
- The record's own path keeps working. A page with the custom URL
/summer-salestill answers at/campaigns/2026/summer, and neither address redirects to the other. If only one should exist, add a redirect from the other as a rewrite, and set the canonical URL in the record's SEO settings. - Links switch to the custom URL.
getFullPath()returns the custom URL whenever one is set, so every link the templates build from the record uses it.getOriginalFullPath()returns the record's own path and ignores it. - Children follow. A page's custom URL does not change its children's addresses, but because of the prefix match,
/summer-sale/termsreaches the childtermsof that page too.
When to use one, and when not
| Case | Use |
|---|---|
A short or printed address for a page deep in the tree: /win on a flyer | A custom URL. The page keeps its place in the tree and its breadcrumbs |
A listing at a friendlier address: /blog for a blog, /stores already given by a custom entity's path | A custom URL on the blog |
| An address from an old site that must keep working | A redirect, unless the old address must stay in the address bar |
| A page whose slug changed | A redirect (Slugs) |
A redirect leaves one address that search engines and links converge on. A custom URL gives a second address that serves the same content, which is what you want for a vanity URL and not what you want for a moved page.