--- title: Enabling alternative URLs for pages related: - https://docs.kentico.com/13/developing-websites/implementing-routing/custom-routing-using-url-patterns.md - https://docs.kentico.com/13/managing-website-content/working-with-pages/managing-page-urls.md --- > Agent instructions: > **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown. > > - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version. > - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt). Pages on Xperience sites have their URLs determined in one of the following ways: - Generated automatically by the system based on the page's position in the content tree (see [Content tree-based routing](https://docs.kentico.com/13/developing-websites/implementing-routing/content-tree-based-routing.md)) - Manually by routes registered in the live site application (together with matching [URL patterns](https://docs.kentico.com/13/developing-websites/implementing-routing/custom-routing-using-url-patterns.md) for page types) In addition to these main URLs, you can configure the system to support alternative URLs for pages. The feature allows individual pages to become available under any number of URLs. Depending on the site's configuration, the system either redirects to the page's main URL or displays the page content under the submitted alternative URL (URL rewrite). Alternative URLs are managed directly in the administration interface, so they can be added or modified without changes in the application's routing code. This makes it possible for content editors and marketers to provide shorter and more relevant-looking links to your website's pages. For example, in a scenario where a website displays an article page with the following URL:\ _/Articles/Products/NewProducts_ Marketers could add an alternative URL and make the article page available under a shorter URL like:\ _/NewProducts_ To set up alternative URL functionality for your website's pages, perform the following steps: 1. [Enable the alternative URLs feature in your live site application](#enabling-the-alternative-urls-feature) 2. [Configure the alternative URLs editing interface and set guidelines for users](#configuring-the-alternative-urls-editing-interface) 3. [Set the alternative URLs mode (redirection or URL rewrite)](#setting-the-alternative-urls-mode) ## Enabling the alternative URLs feature To allow alternative URLs for pages, you first need to enable the feature in the code of your live site project: **MVC 5 development model.** Applies only when building with ASP.NET MVC 5. If this page also covers ASP.NET Core, that version is in its own block. 1. Open your MVC project in Visual Studio. 2. Enable the alternative URLs feature at the start of your application's life cycle, for example in the **Application\_Start** method of your project's **Global.asax** file. > **Info:** MVC projects created by the [installer](https://docs.kentico.com/13/installation/installing-xperience.md) contain the _ApplicationConfig_ class, whose _RegisterFeatures_ method is called in the _Application\_Start_ method by default. You can use this class to encapsulate all of your _ApplicationBuilder_ code (enabling and configuring of Xperience MVC features). > **Note:** **Note**: The feature must be enabled **before** you register routes into the application's _RouteTable_. The _Kentico().MapRoutes()_ method adds routes that handle the alternative page URLs when the feature is enabled. 3. Prepare a **PageRoutingOptions** object with the **EnableAlternativeUrls** property set to _true_. 4. Call the **UsePageRouting** method of the _ApplicationBuilder_ instance, with the _PageRoutingOptions_ object as the parameter. > **Note:** **Content tree-based routing** > > Enabling alternative URLs also by default enables the [Content tree-based routing](https://docs.kentico.com/13/developing-websites/implementing-routing/content-tree-based-routing.md) functionality on the side of the MVC application. If you wish to enable only alternative URLs, set the **EnableRouting** property of the **PageRoutingOptions** object to _false_. ```csharp using Kentico.Content.Web.Mvc.Routing; using Kentico.Web.Mvc; ... protected void Application_Start() { ... // Gets the ApplicationBuilder instance // Allows you to enable and configure selected Xperience MVC integration features ApplicationBuilder builder = ApplicationBuilder.Current; // Enables the alternative URLs feature builder.UsePageRouting(new PageRoutingOptions { EnableAlternativeUrls = true }); ... } ``` The alternative URLs feature is now enabled. The _Kentico().MapRoutes()_ method called in your MVC application's _RouteConfig_ registers routes matching the alternative URLs that users set for pages in the Xperience administration. **ASP.NET Core development model.** Applies only when building with ASP.NET Core. If this page also covers MVC 5, that version is in its own block. 1. Open your live site project in Visual Studio. 2. Edit your application's startup class (**Startup.cs** by default). 3. [Enable](https://docs.kentico.com/13/developing-websites/developing-xperience-applications-using-asp-net-core/starting-with-asp-net-core-development/enabling-xperience-features-in-asp-net-core-applications.md) the alternative URLs feature. 4. Prepare a **PageRoutingOptions** object with the **EnableAlternativeUrls** property set to _true_. 5. Call the **UsePageRouting** method of the _IFeaturesBuilder_ delegate passed to the _IServiceCollection.AddKentico_ method within _ConfigureServices_, and specify the _PageRoutingOptions_ object as the parameter. > **Note:** **Content tree-based routing** > > Enabling alternative URLs also by default enables the [Content tree-based routing](https://docs.kentico.com/13/developing-websites/implementing-routing/content-tree-based-routing.md) functionality on the side of the live site application. If you wish to enable only alternative URLs, set the **EnableRouting** property of the **PageRoutingOptions** object to _false_. ```csharp using Kentico.Content.Web.Mvc.Routing; using Kentico.Web.Mvc; ... public void ConfigureServices(IServiceCollection services) { ... // Enables and configures Xperience features services.AddKentico(features => { // Enables the alternative URLs feature features.UsePageRouting(new PageRoutingOptions { EnableAlternativeUrls = true; }); ... }); ... } ``` The alternative URLs feature is now enabled. The _Kentico().MapRoutes()_ method called in your application's startup pipeline registers routes matching the alternative URLs that users set for pages in the Xperience administration. To ensure that conflicts do not occur with your other routes, you need to configure restrictions and guidelines for alternative URLs (excluded URLs). The related settings for the alternative URLs editing interface are described in the [following section](#configuring-the-alternative-urls-editing-interface). ## Configuring the alternative URLs editing interface After enabling alternative URLs in your live site application, you need to set up the related editing interface for content editors and marketers in the Xperience administration interface. ### Enabling the editing interface 1. Open the **Settings** application in the Xperience administration. 2. Navigate to the **URLs and SEO** category in the settings tree. 3. Under the **Alternative URLs** section, select the **Enable editing interface** checkbox. 4. Click **Save**. Users can now add and edit alternative URLs in the **Pages** application (after selecting a page in _Edit_ mode, on the _Properties -> URLs_ tab). See [Managing page URLs](https://docs.kentico.com/13/managing-website-content/working-with-pages/managing-page-urls.md) for details. The setting only controls the visibility of the editing interface. Any existing alternative URLs remain functional even if you disable the setting (as long as the alternative URLs feature is enabled in the related live site application). > **Info:** **Additional requirements** > > - Alternative URLs are only available for pages whose [page type](https://docs.kentico.com/13/developing-websites/defining-website-content-structure/managing-page-types.md) has the **URL** feature enabled. Pages without a URL typically only store content and do not represent actual pages on the website. > - To work with alternative URLs, users need to have the **Manage alternative URLs** [permission](https://docs.kentico.com/13/managing-users/configuring-permissions.md) for the **Content** module. ### Restricting alternative URLs Giving unlimited control over URLs to end users is typically not desired (this could lead to broken URLs or conflicts). It is important to set guidelines that make it easy and safe for the website's users to add alternative URLs. To configure alternative URL restrictions, use the following settings in the **URLs and SEO** category of the **Settings** application: | Setting | Description | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Excluded alternative URLs | A list of text values specifying restricted alternative URL paths (without the prefix of the site's _Presentation URL_). If a user attempts to add an alternative URL matching one of the specified values, the system prevents the creation and displays the error message specified in the _Alternative URLs error message_ setting.
Every path value must be entered on a new line. The comparison is case-insensitive.
If you need to exclude a large number of URL paths, you can add the asterisk ('\*') character as a wildcard to the **start** or **end** of values. The wildcard represents any number of characters.
Examples:
articles – the _articles_ URL path
articles\* – all URL paths that start with _articles_
articles/\* – all URL paths whose first segment is _articles_
\*articles – all URL paths that end with _articles_
\*articles\* – all URL paths that contain the word _articles_
**Note**:
The system automatically excludes certain URLs paths, for example paths starting with _cms_, _getmedia_ or _getfile_. Such URLs are reserved for page preview links, file requests, internal on-line marketing logging routes, etc.
We recommend excluding the URLs paths of any custom routes in your live site application's routing table that are not used for the main URLs of content tree pages. Otherwise a conflicting alternative URL may override an important route on your website.
If you modify the setting, any existing alternative URLs that match the excluded values **remain in the system** (visible in the _Pages_ application), but are **no longer handled** in the routing of the live site application. | | Alternative URLs constraint | A [regular expression](https://en.wikipedia.org/wiki/Regular_expression) that restricts which alternative URLs are allowed. The expression is matched against the alternative URL path value (without the prefix of the site's _Presentation URL_). If a user attempts to add an alternative URL that does not match, the system prevents the creation and displays the error message specified in the _Alternative URLs error message_ setting.
Use the constraint to define which characters are allowed in alternative URLs or to enforce some type of structural pattern.
By default, the setting contains a pattern that allows upper and lower case alphanumeric characters, underscores ('\_'), hyphens ('-'), and forward slashes ('/'). The default constraint is represented by the following regular expression: ^\[\w\\-\\/]+$
If you modify the setting, any existing alternative URLs that do not match the constraint **remain active** and **continue to be handled** in the routing of the live site application.
**Warning**: We do not recommend allowing characters that have specific meanings in URLs (such as '?' or '#'). This could cause users to submit values that result in invalid URLs or incorrect behavior. | | Alternative URLs error message | The text displayed in the _Pages_ application when a user attempts to add an alternative URL that either matches an excluded URL or does not fulfill the requirements of the URL constraint.
We recommend writing a user-friendly message that describes how to add suitable alternative URLs according to the restrictions configured for your website. | ### Alternative URL validation and main page URL conflicts When users add alternative URLs in the _Pages_ application, the system automatically prevents the creation of any URLs that would be in conflict with other alternative URLs or the main URLs of existing pages on the site. If your system is configured to use custom routing based on the [URL patterns](https://docs.kentico.com/13/developing-websites/implementing-routing/custom-routing-using-url-patterns.md) of page types, URL conflicts can occur after creating a new page or editing an existing one, if the new main URL matches an existing alternative URL on the site. In these cases, the system does not stop the creation or update of the page. However, the _Pages_ application displays a URL conflict warning when viewing such pages. You can also keep track of URL conflicts by monitoring the [event log](https://docs.kentico.com/13/developing-websites/troubleshooting-websites/working-with-the-system-event-log.md). The system provides a site-specific [scheduled task](https://docs.kentico.com/13/configuring-xperience/scheduling-tasks.md) (_Validate alternative URLs_), which runs once per day by default and logs the following into the event log: - Errors for any alternative URLs in conflict with the main URLs of pages on the site. For example, such conflicts can occur after updating a page type URL pattern or creating a new page. In this case, the **alternative URL overrides the main URL** in the routing of the live site application. - Errors for any alternative URLs that match the values of the _Excluded alternative URLs_ setting. This can occur after changing the value of the setting. In this case, the alternative URL **remains in the system** (visible in the _Pages_ application), but is **not handled in the routing** of the live site application. - Warnings for any alternative URL that do not match the _Alternative URLs constraint_ setting. This can occur after changing the value of the setting. In this case, the alternative URL remains active and **continues to be handled in the routing** of the live site application. If your site's pages are under [workflow](https://docs.kentico.com/13/configuring-xperience/configuring-the-environment-for-content-editors/configuring-workflows.md), the main URLs of pages could be different between the published (live) and currently edited versions of pages. The _Validate alternative URLs_ scheduled task evaluates the published versions of pages, while the validation rules and warnings in the _Pages_ application check the latest edited versions. ## Setting the alternative URLs mode The system offers two ways of handling requests that target alternative page URLs: - **Redirect** – the system performs a redirect (with the [301 HTTP status code](https://en.wikipedia.org/wiki/HTTP_301)) to the main URL of the given page. - **Rewrite** – the alternative URL remains presented in the visitor's browser. The system rewrites the URL internally to the page's main URL, so that it can be served by the live site application. To configure the mode: 1. Open the **Settings** application in the Xperience administration interface. 2. Navigate to the **URLs and SEO** category in the settings tree. 3. Under the **Alternative URLs** section, select the required option in the **Alternative URLs mode** setting. 4. Click **Save**. The rewrite option is often preferred by content editors and marketers who want to present shorter or more relevant URLs to visitors. However, rewritten alternative URLs lead to [duplicate content](https://en.wikipedia.org/wiki/Duplicate_content) issues, which can have a negative impact on the site's search engine optimization (SEO). To prevent duplicate content issues with the rewrite option, we strongly recommend that you render pages with canonical link elements. See [Providing canonical URLs for pages](#providing-canonical-urls-for-pages). ### Providing canonical URLs for pages If you use the _Rewrite_ alternative URLs mode, we strongly recommend that you render pages with [Canonical link elements](https://en.wikipedia.org/wiki/Canonical_link_element). Canonical links specify the "main" or "preferred" URL for each page. The Xperience API provides the **Kentico().PageCanonicalUrl()** extension method, which you can use to build the URL (_href_ value) of canonical links. - The method is available via the standard [UrlHelper](https://docs.microsoft.com/en-us/dotnet/api/system.web.mvc.urlhelper) in Razor views. - In cases where an alternative URL rewrite occurred, the method returns the **main URL** of the currently displayed page. The URL is in absolute format. - The main URL is either determined by [content tree-based routing](https://docs.kentico.com/13/developing-websites/implementing-routing/content-tree-based-routing.md), or resolved for the specific page based on the page type's [URL pattern](https://docs.kentico.com/13/developing-websites/implementing-routing/custom-routing-using-url-patterns.md). - For [linked pages](https://docs.kentico.com/13/managing-website-content/working-with-pages/copying-and-moving-pages-creating-linked-pages.md), the method returns the main URL of the original page. - If an alternative URL rewrite did not occur, the method returns the current request URL. > **Note:** **Page data context required** > > For pages on sites that use [content-tree based routing](https://docs.kentico.com/13/developing-websites/implementing-routing/content-tree-based-routing.md), the _PageCanonicalUrl_ method works automatically. > > For pages [handled by custom routes](https://docs.kentico.com/13/developing-websites/implementing-routing/custom-routing-using-url-patterns.md) based on page type URL patterns, the _PageCanonicalUrl_ method requires [manual initialization](https://docs.kentico.com/13/developing-websites/implementing-routing/custom-routing-using-url-patterns.md#initializing-the-page-data-context) of the page data context. We recommend adding a canonical link element to all pages, for example into your website's main layout (and any other used layouts). This ensures that content editors can safely add alternative URLs for any page. The following basic example demonstrates how to add a canonical link element to a Razor view: ```csharp title="Example" @using System.Web.Mvc @using Kentico.Content.Web.Mvc @using Kentico.Web.Mvc ... ... @* Renders a canonical link element *@ ``` The canonical URL is in absolute form and works for all pages, based on either the displayed page's main URL (when handling requests targeting an alternative URL) or simply the current request's URI (for standard requests).