---
title: Custom and extensionless URLs
---

> 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).

You can configure the system to use custom URL extensions and extensionless URLs.

Custom URL extensions allow you to change the default _.aspx_ extension to _.html_, _.asp, .php_, or any other value.

For example, instead of the default _http://www.example.com/news_\*.\*_aspx_, you can have URLs ending with ._html_:

_http://www.example.com/news.html_

you can also configure **extensionless URLs**:

_http://www.example.com/news_

To use custom URL extensions, take the following steps:

1. Adjust your web.config or IIS to handle custom extensions
2. [Configure custom URL extensions in the Kentico settings](#setting-custom-urls)

## Configuring IIS to allow custom URL extensions

> **Note:** **Note**: This procedure only works for IIS 7 sites that use an **Application Pool** with **Managed Pipeline Mode** set to _Integrated_.

1. Edit your application's **web.config** file.
2. Find the **** element inside the **system.webServer** section directly under the web.config root (i.e. not under a specific __ element).
3. Set the **runAllManagedModulesForAllRequests** attribute to _true_ for the opening __ tag:

   ```html

   <system.webServer>
     ...
     <modules runAllManagedModulesForAllRequests="true">
       <remove name="WebDAVModule"/>
       <remove name="XHtmlModule"/>
       <remove name="CMSApplicationModule"/>
       <remove name="UrlRoutingModule-4.0"/>
       ...
     </modules>
   ...
   </system.webServer>

   ```

With this modification in your web.config, configure the extensions in the Kentico administration interface. You can also perform additional configuration as described below.

### Optional configuration (recommended)

It is recommended to configure a custom _Page-not-found_ (404) error page when using custom URL extensions, otherwise a blank page may be displayed in some browsers if a user attempts to access a non‑existing resource.

1. In the Kentico administration interface, open the **Settings** application.
2. Select the **Content** category.
3. Enter the URL of the appropriate document or aspx page into the **Page not found URL** setting, for example: _\~/CMSMessages/PageNotFound.aspx._

Please read [Creating custom error handling pages](https://docs.kentico.com/k8/securing-websites/developing-secure-websites/handling-error-messages-securely/creating-custom-error-handling-pages.md) to learn more.

Alternatively, you can add a **** element into the _system.webServer_ section of your **web.config** file according to the following:

```html

<httpErrors existingResponse="Auto" errorMode="Custom">
    <clear/>
    <error statusCode="404" responseMode="ExecuteURL" path="/<Virtual_Directory>/CMSMessages/PageNotFound.aspx" />
</httpErrors>

```

Replace the __ string in the value of the **path** attribute of the **** element with the name of the virtual directory where you run Kentico.

You can also add the following key to the _AppSettings_ section of the web.config file, which ensures that URLs remain the same even after postback.

```html

<add key="CMSUseExtensionOnPostback" value="false" />

```

If you are using trailing slashes (enabled through the **Use URLs with trailing slash** setting in **Settings -> URLs and SEO**), you can use the following extra key to have only extensionless URLs ending with the trailing slash. URLs ending with an extension are rendered without the slash when the key is used.

```html

<add key="CMSUseTrailingSlashOnlyForExtensionLess" value="true" />

```

### Using the cmspages/handler404.aspx page (obsolete)

For the purposes of backward compatibility, you can also set error pages by configuring your IIS manually. This approach is required for sites that use an application pool in _Classic_ **Managed Pipeline Mode**.

1. Open **Start -> Control Panel -> Administrative Tools -> Internet Information Services (IIS) Manager**.
2. Select your website from the tree and open the **Error pages** section.
3. Right-click the **404 error** and select **Edit Feature Settings**.

   > **Note:** If you receive a **Lock violation** message when configuring the following step, proceed to [Troubleshooting custom and extensionless URL configuration](https://docs.kentico.com/k8/configuring-kentico/configuring-page-urls/custom-and-extensionless-urls/troubleshooting-custom-and-extensionless-url-configuration.md).
4. Enter the following values:
   - **Path:** enter the URL of the **cmspages/handler404.aspx** page according to your application's URL.

     - Example: if you run your web project in virtual directory /kentico, you need to enter /kentico/cmspages/handler404.aspx
   - **Path type:** Execute URL
5. Click **OK**.
6. Right-click the **404 error** again and select **Edit**.
7. Select **Execute a URL on this site** and enter the same URL that you entered in step 4. Click **OK**.
8. Go back to step 3 and repeat the same procedure for the **405 error**.
9. Click **OK** in all dialogs to save the changes. It's not necessary to restart the application.

### Setting up extensions in IIS manually (obsolete)

The following approach is also possible, but not recommended and considered obsolete. For example, to use the **.html** extension, go through the following steps:

1. Run **Internet Information Services (IIS) Manager**.
2. Select your website.
3. Open **Handler mappings**.
4. Click to **Add managed handler...** .
5. Enter the following values:
   - **Request path**: \*.html
   - **Type**: System.Web.DefaultHttpHandler
   - **Name**: HTML
6. Click **OK**.

## Setting custom URLs

Once you have performed the required low-level configuration, set the URL extensions in the Kentico administration interface:

1. Open the **Settings** application.
2. Select the **URLs and SEO** category.
3. Type the required extension into the **Friendly URL extensions** setting, for example: _.html_
4. Click **Save**.

Now when you go to the live website, the system renders all URLs in menus and listings with the specified extension. You may need to manually update static links that were created with the default **.aspx** extension.

### Setting extensionless URLs

To configure the system to use URLs without an extension, save an _**empty value**_ into the **Friendly URL extensions** setting.

### Using multiple extensions

You can enter multiple extensions into the **Friendly URL extensions** setting. Use the following rules:

- The first extension is used as the default
- Enter other extensions, separated by semicolons. Pages can be accessed through URLs ending with all entered extensions.
- To allow extensionless URLs in combination with other extensions, enter a semicolon without an extension

Examples:

- **;.aspx** - extensionsless URLs by default, also allows _aspx_
- **.html;.htm;;.asp** - _html_ extension by default, also allows _htm_, extensionless and _asp_

If you enable the **Redirect documents to main extension** setting in **Settings -> URLs and SEO**, the system redirects URLs with non-default extensions to the corresponding URL with the default extension. This can be useful for SEO purposes. For example, if you want to change your site's URL extension, and use the new extension when the pages are accessed from a search engine that has your website indexed with the old extension.

### Document-level extension settings

In addition to the global settings, you can set URL extensions for individual pages. The default extension that appears in the browser address bar when opening pages is always taken from the global settings.

1. Open the **Pages** application.
2. Select the document in the content tree.
3. Switch to the **Properties -> URLs** tab.
4. Select the **Use custom URL extensions** check box.
5. Type the required extensions using the same rules as described above.
6. Click **Save**.

> **Note:** Even if the **Use custom URL extensions** option is disabled, files (**cms.file** documents) can be accessed under their physical extensions.