Skip to content
TYPO3 Routing: speaking URLs per Site Configuration

Site Configuration as a base for Routing in TYPO3 v9

TYPO3 9.5 supports 'speaking URLs' natively. And all you need is a Site Configuration.

This tutorial will explain the basic setup of a Site Configuration. After that we can deal with an important part of Routing Enhancers: the Extbase Plugin Enhancer. If you're already familiar with Site Configurations, you can skip this tutorial.


'Speaking URLs' are optimized, human-readable addresses of a website. In the past, you had to use third-party extensions like RealURL or CoolURI to get rewritten URLs in TYPO3. But the new version 9.5 LTS is able to manage these out-of-the-box.

Some facts about the new Routing:

  • It is based on the Symfony Routing Component.
  • The routing of pages is enabled as soon as you configured a Site Configuration ("" instead of "").
  • With a Site Configuration, all pages will receive a new field in the page properties: the URL Segment (which is generally comparable with the former realurl_pathsegment).
  • Translations of pages are handled, too.
  • You'll need so-called Routing Enhancers to rewrite Extbase plugins (like News) or other URL parameters.
  • Routing Enhancers are added manually to the Site Configuration (config.yaml).

As the handling of translated pages has changed fundamentally in TYPO3 v9, RealURL will not support this or future versions of TYPO3! So it's about time to deal with the new Routing in TYPO3.

Benefits and scope of the Site Configuration:

  • Convenient management of multiple websites within a TYPO3 installation (all pages with setting is_siteroot).
  • Setting up languages and fallbacks per website. Very useful: You can add language abbreviations to the existing domain ('') or even assign a different domain to a language ('').
  • Handling of HTTP error codes (e.g. 'Display content from Page' or a custom Fluid template).
  • Also useful: the so-called Static Routes allow, for example, to provide a different robots.txt for each site.
  • All configuration of a website is stored in a single YAML file.
  • Domain Records become superfluous.

Setting up a new Site Configuration

Open the TYPO3 backend module 'Site Management > Sites'. All root pages get listed here. Click the button 'Add new site configuration for this site' to do just that.

The mandatory details of a new Site Configuration are as followed:

  1. The Site Identifier (this will be the name of a new subdirectory in typo3conf/sites/, so please note the recommendations given there).
  2. The Entry Point: it's best to use a full URL with protocoll and domain. If you just use a slash there may be issues with the Error Handling! For local development environments you can create variants.
  3. Setting up the language: even if your website only uses a single frontend language, this has to be configured! This information is used by TYPO3 to e.g. render the HTML tag (<html lang="en">).

I restrict myself to the necessary configuration for the Routing. You can find further information about the possibilities here:

After you saved your Site Configuration you can find it in /typo3conf/sites/your_identifier/config.yaml

The created config.yaml will look something like this:

rootPageId: 7
base: ''
    base: 'http://mydomain.test/'
    condition: 'applicationContext == "Development"'
    title: English
    enabled: true
    languageId: '0'
    base: /
    typo3Language: default
    locale: en_US.UTF-8
    iso-639-1: en
    navigationTitle: English
    hreflang: en-US
    direction: ''
    flag: en-us-gb
errorHandling: {  }
routes: {  }

Wait a minute! 'applicationContext'?

For local development I specified an alternative Entry Point (baseVariants). This will be used if TYPO3 is running in the given applicationContext, which can be set e.g. in a .htaccess file. The default .htaccess of TYPO3 already has some rules prepared which you can adapt and activate:

  RewriteCond %{HTTP_HOST} ^mydomain\.test$
  RewriteRule .? - [E=TYPO3_CONTEXT:Development]

The current Application Context status can be checked in the TYPO3 Backend by opening the Application Information (topbar):

Besides, you can use baseVariants in the config.yaml for your website's languages, too. An example can be found in the associated changelog entry.

About the URL Segment

If a Site Configuration is present, TYPO3 will automatically create URL Segments for the associated page tree.

For this, the page title will be copied and converted to lowercase letters. Spaces are replaced by hyphens, special characters are omitted.

Optimized, human-readable URL paths are also called slugs, especially in the field of Search Engine Optimization (SEO).

If two or more pages on the same level in the page tree share the same name, TYPO3 will add suffixes to the URL Segments in order to keep all URL paths unique (e.g. /pagetitle-1).

All URL Segments can be customized in the page properties:

  • You can either use a button to automatically recalculate the path by the current page title(s)
  • or entirely by hand

This way, you could have a subpage in the page tree under 'Bookselling > Non-Book > Poster', but set the speaking URL to ''. Or something entirely different.

And of course there are dedicated fields for URL Segments of translated pages.

FAQ about the new TYPO3 Routing

Some use cases are not yet covered by the new Routing feature. But of course improvements are already planned and worked on. For instance it's planned, when a user changes a page title, that he will get prompted to choose between a) keeping the old URL Segments or b) to automatically create redirects for the old paths.

Does the URL segment change when I rename a page?

Not automatically. You'd have to update it manually in the page properties. An automatic approach would result in broken URLs, which is bad for your SEO ranking. If you manually change paths, you should set up proper redirects in the new Backend module 'Redirects' afterwards.

How can I update the URL Segment of all subpages (at once) after renaming a parent page?

Again, the TYPO3 core currently does not support this automatically. You will have to update the slug for every single page. Unfortunately, it's also not possible to change the URL segments together in the Single Table View (at least the 'recalculate' button doesn't work). It seems that TYPO3 lacks the necessary context there.

But there are two extensions which could help you managing your slugs:

Can I exclude a page completely from the URL Segment of its subpages?

Only manually, one by one. Currently it's not supported to exclude a normal page from slug generation. A possible workaround: page types with a doktype value of 200 or higher are always ignored in URL Segments. These are folders, menu separators (spacer) and recycler. Keep in mind though that these page types cannot be called in the frontend!