Kentico CMS 7.0 Developer's Guide

URL format and configuration

URL format and configuration

Previous topic Next topic Mail us feedback on this topic!  

URL format and configuration

Previous topic Next topic JavaScript is required for the print function Mail us feedback on this topic!  

Defining URL extensions

Page URLs can use various types of extensions. By default, all URLs end with .aspx, for example:

You can also use custom extensions, such as .htm, .html or any other sequence of characters. Alternatively, you can even use URLs without extensions, such as In this case, you need to configure the system as described in the Configuration of custom URL extensions chapter.

Forbidden URL characters


Certain characters have special meanings when they are found in a URL, so they cannot be used in values that determine the path to pages (i.e. document aliases and URL paths). By default, the following characters are forbidden:


\/:*?"<>|&%.'#[]+=„“ and the space character.


If needed, you can add additional forbidden characters by entering them (without any separator) into the Forbidden URL characters setting in Site Manager -> Settings -> URLs and SEO. Alternatively, a regular expression may be entered as the value of the Allowed URL characters setting to precisely specify which characters should be allowed in URLs.


Please note that the default characters listed above will always be forbidden unless you override them through the CMSForbiddenURLValues key, which can be added to the /configuration/appSettings section of your application's web.config file. For example:


<add key="CMSForbiddenURLValues" value="$\/:?&quot;&lt;&gt;|&amp;%.&apos;#[] =" />


Through this key, you may either allow some of the default forbidden characters or add new ones. It is recommended to keep the default characters forbidden, since they may prevent certain types of URLs from working correctly if entered into URL paths.


Forbidden characters are automatically replaced or removed. You can specify the character that is used to replace forbidden characters through the Forbidden characters replacement setting in Site Manager -> Settings -> URLs and SEO. By default, forbidden characters located at the beginning or end of the path are removed completely and consecutive forbidden characters are only replaced by a single character. If you wish to have each forbidden character replaced individually, you can add the following key to your web.config:


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


This preference may also be set specifically for the Document URL Path property of documents (and no other URLs) via the key below:


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





Advanced character replacement customization


It is also possible to change the character replacement behavior to deal with specific scenarios, such as handling non-ASCII character sets or assigning unique replacement strings for specific characters.


This can be achieved by customizing the process used to convert URLs into a safe format. Please see Custom handling of URL path values for more information.


Using URL Prefixes

If you need to add a prefix to all URLs on a specific site (e.g. for search engine optimization), you can specify it in the Site Manager -> Settings -> URLs and SEO -> Default Url Path Prefix field. The URLs will then use the following format: <domain>/<path prefix>/<document URL path>


For example:


Automatic creation of new document aliases


If you check the Site Manager -> Settings -> URLs and SEO -> Remember original URLs when moving documents check-box, new document aliases will automatically be created when a new extension or URL path is set.

Using language prefixes for URLs


If you wish to add a different URL prefix for every document culture version, you can specify it in the Site Manager -> Settings -> URLs and SEO -> Use language prefix for URLs field. If you have both language prefixes and standard URL path prefixes enabled, the standard URL prefix always precedes the language prefix in the URL. Please refer to the Multilingual and international support -> Languages and URLs topic for more details.
URL related settings

The above configuration tasks can be performed in Site Manager -> Settings -> URLs and SEO. The following table shows an overview of the available settings:

URL format

Forbidden URL characters

List of additional characters that cannot be used in URLs (document aliases and URL paths). The following characters are forbidden by default: \/:*?"<>|&%.'#[]+=„“ and the space character.

Forbidden characters replacement

Specifies the character that the system uses as a replacement for forbidden characters in URLs.

Allowed URL characters

Determines which characters are usable in URLs by means of a regular expression. Any characters not specified are forbidden. If empty, only the characters specified by the Forbidden URL characters setting are prohibited.


When allowing special characters in the regular expression, they must be preceded by a backslash (\) as an escape character.


Example: Entering a-zA-Z0-9\^ as the value only allows alphanumeric characters and the caret symbol (^) to be used in URLs.

Friendly URL extension

Specifies the extensions that the system adds to document URLs.


Extensions must be preceded by the period character.

You can add multiple extensions separated by semicolons (;).

The first extension is used as the default option when generating links and page URLs. Additional extensions are supported in URLs when accessing documents.

To allow extensionless URLs, enter a semicolon without any extension.


Sample value: .aspx;.html;.htm;;

Files friendly URL extension

Specifies the extension that the system adds to file URLs.


Example: getfile/<node alias>/myimage.aspx


If empty, the file URLs end with no extension: getfile/<node alias>/myimage

Excluded URLs

Specifies a list of URLs that are excluded from the URL rewriting engine. See Excluding URLs from the rewriting engine for more information.

Document URLs

Default URL path prefix

Defines a default URL path prefix that will be used for all URLs of the content pages. Internally, this prefix is rewritten to the urlpathprefix query string parameter.

Use name path for URL path

If checked, a document's name path will automatically be copied to its URL path.

Use permanent URLs

If enabled, URLs of documents and document attachments will be generated in permanent format. If disabled, friendly URLs will be used. Learn more in the Linking pages and files topic.

Remember original URLs when moving documents

Determines if new document aliases should be created when a new document URL path or extension is set.

Automatically update document alias

If enabled, the alias of a document is automatically updated to match any changes in the name of the given document in the default culture. Also, the document alias property will not be editable manually.

Other settings (related to SEO) may also affect the format of URLs. To learn about these, please refer to the Search engine optimization chapter.