Vanity URLs & URL Rewriting

Vanity URLs are alternate reference paths to internal or external URL's, and can be simple but powerful tools to aid in site maintenance and SEO. 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.

Using Vanity URLs

You may use Vanity URLs to redirect to any of the following:

• Pages
• Files (including images)
• URL Mapped content items
  • In other words, the URL that displays an individual URL-mapped content item
• Multiple pages, files, or URL Mapped content items (using a regular expression).

You may not use Vanity URLs to redirect to any of the following:

• Individual content items (except when URL Mapped to a specific URL).
• The Detail page of a URL Mapped Content Type.

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 following table provides examples of how to use Vanity URLs to redirect to different types of locations:

¹ = Another dotCMS site on the same dotCMS instance.
² = Any site not on the same dotCMS instance (even another dotCMS site, if it's not on the same dotCMS instance).

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 (www.dotcms.org/documentation) has been created that will display the page http://dotcms.org/documentation/latest/table-of-contents:

The above image randered in plaintext:

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

Important Notes

• Vanity URLs may only contain valid URL characters.
• All letters in Vanity URLs will be forced lower-case letters.
• When redirecting TO a file or page, the Vanity URL will work correctly whether or not the Uri field includes a trailing slash (/).
  • BUT to access the Vanity URL from the browser, the Uri will not be recognized if it includes a trailing slash (whether or not the Uri field includes one).
• You may redirect to a page or file in any folder on your site (even one which is within a folder which is not set to Show on Menu).

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

Forward (200)

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

Redirect (301 and 302)

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 with a 301 or 302:

• 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).
  • This ensures that all relative links on the page work properly after the redirect.

301 Redirect vs. 302 Redirect

Although the dotCMS behavior for 301 and 302 redirects is almost identical (other than the HTML response code), there are some differences in how other applications treat these response codes:

• Some search engines treat these response codes differently.
  • So the choice of a 301 or 302 redirect may affect your SEO results.
    • For more information, please see Search Engine Optimization, below.
• Many browsers cache 301 redirects locally (in the browser).
  • So if users have already been redirected once using a 301 Vanity URL, their browsers may still redirect them, even after you change or unpublish the Vanity URL.
  • Since this behavior happens in the users' browser, not dotCMS, the only way to prevent this behavior is for the user to clear their browser cache.

Redirecting Multiple URLs Using Regular Expressions

You may configure a single Vanity URL to match multiple URLs by using a regular expression (also known as a “regex”) as part of the Uri field. The Vanity URL will match all URLs which match the regular expression in the Uri field, and will replace them with the URL specified in the Forward To field.

If you put a simple string in the Forward To field, then all URLs which match the regular expression will forward to the single Forward To URL. However you can also specify parameters in the Uri field regular expression, and then copy the values of those parameters into the URL specified in the Forward To field.

• To specify a parameter in the Uri field, surround the regular expression to match with parentheses (()).
  • You may include up to 9 parameters in the Uri field, each surrounded by parentheses.
• To include the value of a matching parameter in the Forward To field, use a dollar sign followed by the number of the parameter (starting with number 1, in the order the parameters appear in the Uri field).

For example, if your Uri field is /products/([A-Za-z0-9]+)/([0-9]+) then:

• A $1 in the Forward To field will be replaced with the part of the URL that matches the regular expression ([A-Za-z0-9]+).
• A $2 in the Forward To field will be replaced with the part of the URL that matches the regular expression ([0-9]+).

Example: Moving a Top-Level Folder

The following example values redirect all URLs pointing to the top-level “/services” folder to a sub-folder named “cloud” under the “/products” top-level folder.

In plaintext:

Using this type of a regular expression parameter in your Vanity URL enables you to move folders within your site freely, creating a single Vanity URL to redirect any requests that go to any pages or files in the old location of the folder.

Evaluation Order

Although it does not make sense to create multiple URLs with the same value for the Uri field, there may be cases where you create multiple Vanity URLs which match the same page when using regular expressions in one or more of Vanity URLs.

dotCMS evaluates Vanity URLs in the order specified by the Order field. When two Vanity URLs both match the same page, dotCMS evaluates the Vanity URL with the lower order value.

Example:

For example, you may create a Vanity URL without a regular expression to redirect a specific page, but have another Vanity URL which uses a regular expression to redirect all pages within the same folder that the redirected page used to be located in.

The following two Vanity URLs are created:

If a link points to /documentation/doc-request, then the Uri fields of both these Vanity URL fields match the link URL. To ensure that the “Page Redirect” Vanity URL is matched (instead of “Folder Redirect”), the Order field of “Page Redirect” must be lower than the Order field of “Folder Redirect”.

• If the Order of the “Folder Redirect” is lower than the Order of “Page Redirect”, the “Page Redirect” Vanity URL will never get matched.
• If the Order fields of both Vanity URLs are the same, then it is undetermined which Vanity URL will be matched (and the results may be unpredictable, especially after a reindex).

Only One Vanity URL is Matched

It is important to note that only one Vanity URL will be matched for any URL. This means that you can not “chain” Vanity URLs (so that the Forward To field of the first matching Vanity URL then matches the Uri field of another Vanity URL), regardless of the evaluation order.

Example:

The following two Vanity URLs are created:

If a link points to /documentation/doc-request, only the first Vanity URL (Page Redirect) is evaluated, so the link evaluates to /documentation/request (and not to /docs/request, which would require both Vanity URLs to be evaluated).

Vanity URLs and URL Maps

It is also important to note that although two Vanity URLs will not be evaluated for a URL, a Vanity URL can forward to URL mapped content.

Example:

1. An “Office” Content Type exists which has a “URL Title” field and a URL Map Pattern of /locations/{urlTitle}.
2. The following Vanity URL is created:

If a link points to /about-us/offices/miami, the Vanity URL will redirect to /locations/miami, and then the URL Map will also be evaluated to display the URL Mapped “Office” content (the “Office” content item with miami in the URL Title field).

Permissions

The Permissions on a Vanity URL itself determine which users can access the URL specified in the Vanity URL URI field. These permissions do not have any effect on the permissions of the object (page, file, path, etc.) that the Vanity URL redirects to in the Forward To field.

For a user to access any object via a Vanity URL, the user must have permissions to view both the Vanity URL and the object the Vanity URL redirects to.

For example, if the permissions on a page are restricted to prevent anonymous users from viewing the page, and you create a Vanity URL which redirects users to that page, anonymous users will still not be able to view that page, even if the Vanity URL permissions are set to allow anonymous users to access the Vanity URL.

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
• /DOTSASS
• /DOTLESS

Search Engine Optimization (SEO)

Canonical URL

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.

301 vs. 302 Redirects

Some search engines may reduce the ranking of pages which are redirected using 3xx redirects (either 301 or 302). Note, however, that Google no longer reduces Page Rank for 301 or 302 redirects, but some other search engines may still reduce ranking for 301 or 302 redirects.

In addition, some search engines (including Google) may sometimes pass less link credibility (or “link juice”) when using a 302 redirect than when using a 301 redirect. Therefore, to maximize SEO, it is recommended that you use a 301 redirect for any Vanity URLs which are intended to be permanent (or long-lasting), and only use a 302 redirect for Vanity URLs which are truly intended for temporary use (such as for a time-limited promotion or temporary redirect while a page or application is updated).

Troubleshooting

If you have a Vanity URL which is not redirecting as expected (either not redirecting at all, or redirecting to a different location than you expect), the following troubleshooting steps can help you identify and resolve the most common errors with Vanity URL configuration.

1. Ensure the Vanity URL is published.
   • In addition, if you use Push Publishing, verify that the Vanity URL has been pushed to the receiver. You can see the Push History in the Vanity URL History tab.
2. Verify that you are using the correct format for the Forward To field.
3. Verify that you are using the correct redirect type.
   • Specifically, you may not use a forward (200) when redirecting to an external site.
4. Check for Multiple Matches
   • It's possible that you have multiple Vanity URLs matching the same URL.
   • Search for all Vanity URLs which match a portion of the matching Uri field:
     • In the Content Search screen, select Advanced on the left sidebar to display all search fields, and type the first part of the matching URL into the Uri field in the sidebar.
   • If you have multiple matches, check the order of evaluation.
   • You may wish to edit the Vanity URL Content Type to enable the Show in List property of the Order field.
5. Clear your browser cache.
   • Your browser may be displaying a cached version of the page from before the Vanity URL was implemented.
6. Reindex the Vanity URLs
   • Select System -> Maintenance and click the Index tab.
   • In the Reindex field, select Vanityurls.
   • Press the Reindex button.