Using vanity URLs (Site settings SEO)

November 14, 2023

What is a vanity URL?

Vanity URLs (also known as Friendly URLs) are additional, customizable and unique web addresses for pages and contents, which are useful for the website visitor to remember a specific page. It is also very important for search engines, as they are used to describe the content of the page. It also make things easier for your marketing campaigns. More details about Vanity URLs are available on

For example, the following URL 

can be converted into

How can Jahia help me with vanity URLs?

By default, the URL of a page in Jahia is built by using the technical names of the pages, and by following the structure of the site. For instance, if you have a page “About” under the homepage of your site, you will access it with the following URL: https://domainname/home/about.html. The more levels you have in your site, the longer the URL will be. So if you have a page “History” under the About page, then its URL will be: https://domainname/home/about/history.html 

To shorten such URL, make them more user friendly, and/or to work on the Search Engine Optimization (SEO), you can manually add custom URLs, Vanity URLs, to your page. The only constraint is that the value chosen for theses URLs must be unique on your site.

For instance, you can add the following vanity URLs for the “History” page:

  • /history
  • /company-roots
  • /how-it-started

The page will then be available using any of the following URLs:

  • https://domainname/home/about/history.html
  • https://domainname/history
  • https://domainname/company-roots
  • https://domainname/how-it-started

It is also possible to specify a canonical/default vanity URL, which will be used in the navigation menus, when creating links, etc.

When working with several sites, it is possible to have the same value for the vanity since the domain will be different: https://domainname/history & https://otherdomainname/history

Please note that Vanity URLs don't work when working on localhost, which typically happens during development

In a multilingual site

Vanity URLs are also useful for sites available in several languages. Jahia prefixes the path of the page with the corresponding language: the French version of the blog page is available using the following URL:
https://domainname/fr/home/company/events.html. Using vanity URLs allows you to also translate the URL in the given language: https://domainname/fr/societe/evenements

A vanity URL is specific to one and only one language. The unicity of the vanity URL on the site still applies, so you cannot use the same vanity URL for the same page in two different languages. In the previous example, https://domainname/fr/societe/evenements, the “/fr/” has been explicitely added to the Vanity URL by the user, in order to explicitely inform that the page is in French and to ensure consistency for all URLs of the same language.

Where to find vanity URLs management in Jahia?

Vanity URLs can be added on pages and on content items that can be displayed in full page, like news or blog articles (these content items are usually referred as "content templates" or "main resources"). 

It is possible to manage vanity URLs from the following interfaces:

  • Vanity URL panel in Content Editor, when editing pages.
  • Vanity URLs dashboard accessed from jContent>Additional>Vanity URLs
Note: Once a vanity URL has been set on a page in Content Editor or using the Vanity URLs dashboard, a publication of the page or the vanity URL itself is required to activate it in the live version of your site.

On which content types can I add Vanity URLs on?

Vanity URLs can be added to:

  • Pages (content items using the type jnt:page)
  • Content items that can be displayed in full page (content using a type with mixin jmix:mainResource)
  • Files (content using the type jnt:file)
  • If you want to add vanity URLs to content items that are not using these types, it is possible to use the mixin: jmix:canHaveVanityUrls. Developers managing the content type definition can add it to the relevant content types if needed.

Managing vanity URLs when editing a content

The panel to manage and edit the vanity URLs is available when editing pages or files in the 3 dots menu, at the top right of the Content Editor form. 



Editing vanity URLs for a page / content / file

Adding vanity URLs

Simply click on the Add vanity URL button then start typing the vanity URL, and click Save.


When saving the value, if the vanity URL doesn't start with a slash (/), a slash is automatically added at the beginning. The vanity URL can only contain letters, digits, dots (.), dashes (-) and no consecutive slashes. By default, the language selected for the vanity is the one selected in Content Editor, but it's possible to change it if needed.

Note that the panel displays vanity URLs of all languages for the page. 

Editing a vanity URL

You can edit an existing vanity URL by clicking on it.


An error message is displayed when clicking on the save button in the following cases:

  • The vanity URL already exists on another page
  • The vanity URL contains non valid characters (only letters, digits, dots (.), dashes (-) and no consecutive slashes are allowed).

To change the language of a vanity URL, click on the current language and select the new one in the drop-down.

Publishing / Making your vanity URL active

There are 2 ways to publish a vanity URL (make the vanity URL active on the live version of the site): 

  • Publish the vanity URL, by clicking on the 3 dots on the right of the vanity URL and confirm the publication.
  • Publish the content, file or page associated with the vanity URL

Viewing published / non published values

At the top left of the vanity URL panel, it is possible to switch between "Staging vanity URLs", "Live vanity URLs" and "Staging and Live". It is only possible to edit the staging vanity URLs. To change the values of the live vanity URLs (the ones that are active on the site), you'll need to edit the staging value and then publish.


Status color

If a vanity URL has a green status, it means that it is the same in both edit version and online. In other words, the vanity URL has been published and hasn’t been modified ever since.

The orange status signifies that either the vanity URL has never been published, or that it has been modified since the last publication.

Setting a vanity URL as canonical

The canonical vanity URL defines the vanity URL to use in the navigation menus, links, etc. Only one canonical vanity URL is possible per language and per page/content. Defining a vanity URL as canonical will also automatically add the canonical link tag to the head of the page for the vanity.

A page can only have one canonical vanity URL per language. If no vanity URL is defined as canonical, the path of the page will be used as canonical.

When defining a new vanity URL as the canonical one, then the property is automatically removed on the other vanity URL: It is then advised to publish both vanity URLs at the same time. 

For more information on the hreflang tags, you can scroll to the alternate and canonical section. 

Deleting a vanity URL (before version 4.0)

The deletion of a vanity URL is a two step process:

  1. Deletion in “staging”: Click on the ‘delete’ button trash.PNG. A confirmation window is then displayed. If the vanity URL has never been published, then the vanity URL is fully deleted. If the vanity URL has been previously published, the vanity URL is still functioning in live.
  2. Deletion in "live": Delete the live (published) version of the vanity URL, by going to "live vanity URLs" and clicking on the delete button trash.PNG for the selected vanity. Once done, the vanity URL does not work in live anymore. It is also possible to publish the page (or content or file) to delete the vanity in live.


Warning: It is only possible to delete all the vanity URL for a page in live. Individual deletion in live is not supported.

Deleting a vanity URL (version 4.0 and above)

Deleting a Vanity URLs happens as any other content item in Jahia, it's a 2 steps process

  • Step 1: click on the 3 dots at the right of the vanity URL and then "Delete". Confirm the deletion. At that stage, the Vanity URL is locked and "Marked for deletion".


  • Step 2: If the Vanity URL was previously published, you'll need to publish the deletion. If the Vanity URL was not published, select "Delete permanently".

Note: If a Vanity URL is set as canonical and marked for deletion, it won't be possible to add a new canonical URL until the deletion of the first Vanity URL is published.

Moving a vanity URL

It is possible to move a vanity URL in Content Editor (i.e. in “default”) from a source page to a destination page. The vanity URL will point to the source page until the move of the vanity URL is published or until the publication of the destination page.
In order to move a vanity URL, just move your cursor on the vanity URL and then click on the "move.PNG Move" button. You will then be able to either select a page by browsing the site page tree, or you can directly enter the path of the destination page or content.


Activating or deactivating a vanity URL 

Deactivating a vanity URL means that the vanity URL will not be usable online once it is published. In other words, the page will not be displayed if a visitor uses the vanity URL in their browser. A “404 Page not found error” page will be displayed instead.
To deactivate a vanity URL, simply use the toggle button. You will then need to publish the vanity URL to deactivate it in live as well:

A deactivated vanity URL appears in grey:


In this example “/how-it-started” is deactivated in both edit and live. “/history” has been deactivated in default, but it has not been published yet, so it is still activated in live.

Vanity URLs dashboard

The Vanity URLs dashboard is accessible in jContent>Additional>Vanity URLs.


It lists all the pages and contents which have at least one vanity URL. By clicking on a page or content you will display all its vanity URLs:


Filter per language

The panel displays by default the vanity URLs in all the available languages of the site. It is possible to only display the vanity URLs of one or several languages, by selecting the desired languages in the language selector:


This selector lists the different languages activated on the site.

Filter by keyword

It is possible to filter the pages/contents by searching for part of one of their vanity URL. Then only the vanity URL corresponding to the search terms are displayed, but it is possible to show all the vanity URLs of the page/content by clicking on the Show all button.

Note: Unfortunately, it is currently not possible to search by using the page/content title.

Operations on multiple vanity URLs

It is possible to perform the same operations on several vanity URLs previously selected:

  • Delete
  • Move
  • Publish

It is possible to select vanity URLs from different pages, by selecting the checkbox next to a mapping. The top checkbox allows you to select or unselect all the vanity URLs of a page.
When one or several vanity URLs is/are selected, then the available operations are displayed at the top of the screen:


Canonical and alternate tags

In the HEAD section of html pages, it is considered a good practice to add 2 information related to URLs that will help Google index your site correctly: Canonical and alternate / hreflang. 

By default, since version 3.x of the site-settings-seo module, canonical and alternate hrefland tags are automatically added. Starting in version 4.x, if there is a canonical or an alternate tag in the page, added through the page template or by any other way, then the site-settings-seo module won't add the tags, in order to avoid duplicates.

  • Canonical: This tag helps Google understand which URL is the main one for a given page, for instance <link rel="canonical" href="">. This is helpful in case of content duplication. Note that it is a good practice to include a "self referencing canonical tag": it means that there every page should include a canonical tag, including the page served with the canonical URL. If you want to learn more about the Canonical tag, you can read Google documentation of the canonical tag or an explanation of self referencing canonical tags.
    • The module site-settings-seo will add the canonical tag automatically, for instance <link rel="canonical" href="">. The value of the canonical href link will use the vanity URL defined as canonical, or the language and the path if no canonical URL has been defined for the page.
  • Alternate: This tag is used to inform Google about translations of the page. For more information, you can refer to the documentation of the alternate tag by Google.
    • The module site-settings-seo will also add the alternate href lang tag automatically, for instance <link rel="alternate" hreflang="fr" href="">. If a translation doesn't exist for a language or if the language has been set as not visible, it won't be listed.

Disabling automated generation of canonical and alternate tags

It is possible to disable the automatic generation of canonical and alternate tags, by editing a value inside the configuration file: org.jahia.modules.sitesettingsseo.config.impl.ConfigServiceImpl.cfg.

Set the property enableSEOAutomaticMetaTagGeneration from true to false.


Vanity URLs are not supported on external data providers (EDP), and attempting to set a vanity URL on an EDP node may result in a 404 error.