Vanity URLs - Documentation topics on: alias,redirects,vanity urls,virtual links,virtual path,.

Vanity URLs

Vanity URLs are alternate reference paths to internal or external URL's. When you create a Vanity URL, a user may access the same page or file using two different URLs - the normal path to the page or file as it appears in the Site Browser tree, and the URL specified in the Vanity URL.

Common Uses

Some common uses of Vanity URLs include:

  • Give site visitors a more user-friendly or memorable way of reaching an HTML page or File (which might actually live “buried” in a much deeper path).
  • Redirect URLs to a new location when the path to a page or file has changed.
  • Help track links from different sources (such as different promotions) to the same page on your site.

The Vanity URLs Tool

Vanity URLs may be viewed from either the Content Search tool (Content -> Search) or the Vanity URLs tool (Marketing -> Vanity URLs). Both views display Vanity URLs using the same display format as the Content Search screen.

Adding or Editing a Vanity URL

When creating or editing a Vanity URL, you must give the Vanity URL a Title, select which Host the Vanity URL applies to (or “All Hosts”), and supply a “virtual path” to the destination in the URL field. You can either type in the URL for a link or use the click here to browse button to browse for an internal destination.

Note: Please see Redirect Types, below, for an explanation of how the URL entry affects what type of redirect is performed.

In the example below, a Vanity URL ( has been created that will display the page

Edit Vanity URL

Once you have saved the Vanity URL, test the new “virtual” path by typing it directly into your web browser.


  • Vanity URLs may only contain valid URL characters.
  • All letters in Vanity URLs will be forced lower-case letters.

Redirect Types

Whenever a user accesses the specified URL, dotCMS will either forward or redirect the user to the forward URL. You can perform three different types of redirects with Vanity URLs:

  • 200 Forward
  • 301 Permanent Redirect
  • 302 Temporary Redirect


When you set the redirect type to 200 Forward, dotCMS will perform a “requestdispatcher” forward (a transparent forward) whenever a user accesses the specified URL. The URL in the user's browser will not be changed.

Vanity URLs created in this way are true URL's which maintain their presence in a website browser's navigation toolbar even after the destination HTML page or file is reached.

Important: Since the URL in the user's browser does not change with a forward, if there are links on the destination page which are relative to the destination page itself, these links may not work since they will be referenced from the Vanity URL's URL local (e.g. /documentation) rather than from the actual location of those files in your Site Browser tree (e.g. /docs/latest). To ensure that links in the destination page will work even when a forward is used, you should reference all URLs relative to the root of your Site Browser tree (e.g. “/docs/latest/vanity-urls”) rather than relative to the page or folder the page is in (e.g. just “vanity-urls”).


When you set the Action to a Redirect (either 301 or 302), dotCMS will redirect the user to the Forward to URL whenever a user accesses the specified URI. When the user is redirected, the URL displayed in the user's browser will change to display the Forward To: URL, and all links on the destination page will be referenced from the normal path of the page (as displayed in the Site Browser tree), ensuring that all relative links on the page

Blocked URLs

As a security precaution, certain URLs are not allowed in vanity URLs (e.g. “black-listed”). The following is a list of all URL branches that are not allowed; you will not be allowed to save any Vanity URL which begins with one of these strings:

  • /html
  • /api
  • /dotAdmin
  • /dwr
  • /webdav
  • /dA
  • /contentAsset
  • /c

Search Engine Optimization (SEO)

On Google and some other search engines, the location of your page in search results may change if the same content is available via two different URLs (such as with a Vanity URL and the page the Vanity URL points to). To maximize your page ranking in search results, you may specify the canonical URL for any Page Asset. This directs the search engines to combine the search result data for the main page and any Vanity URLs linked to that page.

To specify the canonical URL, open the Page Properties, select the Advanced Properties tab, and edit the Canonical URL field. Once this field has been set, dotCMS will automatically add a canonical URL link to the page header each time the page is displayed (either directly or through a Vanity URL).

For information on other ways to maximize search engine optimization for pages referenced by Vanity URLs, please see Use canonical URLs on the Google help site.