Study guide · Sites, Routing and SEO

Sites, routing and SEO: From the page tree to a clean address

As of November 15, 2026 · TYPO3 14.3 LTS · about 26 min read

A website needs an address, languages, error pages, readable URLs, redirects and information for search engines. On this page you follow the integrator Mara through the relaunch of the Lindenau music school. Afterwards you know what belongs in the site configuration, how TYPO3 resolves a URL, how redirects work and what the SEO extension does on its own.

The example: the Lindenau music school

The project is a Composer project with TYPO3 14.3. Mara's sitepackage is called lindenau_site, and the Composer package is lindenau/site. The old website had addresses like index.php with a page ID as a parameter. The new one should have readable addresses, such as kurse followed by klavier.

The German website runs under www.musikschule-lindenau.de, and the English version under the path en. For the course directory the team has a small Extbase plugin, and for news the extension news.

The site configuration

In TYPO3, a site is a page tree with its own address. You edit its settings in the backend module Sites > Setup. There you create sites, edit the base URL, languages, error handling and static routes, and choose the site sets.

The form does not write to the database. It writes to a file. Every site has a folder below config/sites, named after its identifier. It contains the file config.yaml, so for Mara's site with the identifier lindenau it sits in the folder config/sites/lindenau. Other files can sit next to it, for example settings.yaml for the site settings or csp.yaml for the Content Security Policy. The folder belongs in version control.

rootPageId: 1
base: 'https://www.musikschule-lindenau.de/'
websiteTitle: 'Musikschule Lindenau'
dependencies:
  - lindenau/site
  - typo3/seo-sitemap
languages:
  - languageId: 0
    title: Deutsch
    base: /
    locale: de_DE.UTF-8
    hreflang: de-DE
    flag: de
  - languageId: 1
    title: English
    base: /en/
    locale: en_GB.UTF-8
    hreflang: en-GB
    flag: gb
    fallbackType: strict
Excerpt from Mara's config.yaml. The root page has the ID 1, and the base URL is the German domain of the music school. The site uses the sitepackage set and the sitemap set. There are two languages: German with the ID 0 under the path slash, and English with the ID 1 under the path en, each with locale and hreflang.

The most important keys:

  • The key rootPageId names the root page of the site.
  • The key base is the base URL, the entry point of the site.
  • Under languages you find the languages, under errorHandling the error pages and under routes the static routes.
  • Under routeEnhancers you find the routing for extensions, and under dependencies the site sets.

On the command line, the command site:show with the identifier shows the complete configuration of a site, including the sets it uses. The command site:list lists all sites, and site:sets:list all available sets.

vendor/bin/typo3 site:show lindenau
vendor/bin/typo3 site:list
vendor/bin/typo3 site:sets:list
The three commands from the paragraph above, for the site lindenau.

Site or site set? A site set provides the reusable part, for example TypoScript for all sites of a design and default values for settings. What belongs only to this one website goes into the site configuration: the base URL, the root page with its rootPageId, and the languages.

Root node and root page

At the very top of the page tree sits the root node, shown with a globe icon. It is level 0 above all pages and has the ID 0. It is not a page and has no entry in the pages table.

Only records that apply to the whole installation live on the root node. Whether a table is allowed there is controlled by the TCA option rootLevel:

  • With the value 1, records are allowed only on level 0. This applies to backend users and backend groups, to file storages in the table sys_file_storage, and to file mounts in the table sys_filemounts.
  • With the value minus 1, they are allowed on level 0 and on pages. This applies, for example, to categories and redirects.
  • With the value 0, the normal case, records belong only on pages or in folders. That is why content elements and frontend users never sit on the root node.

Only administrators may work on level 0, and even they only with tables whose TCA allows it.

Do not confuse this with the root page of a site. It is a perfectly normal page. It sits directly below the root node, so its pid is 0, or it has the property “Use as Root Page”. Its UID is an ordinary number, 1 in Mara's case. When you create a new page on level 0 in the backend, TYPO3 generates a basic site configuration for it right away.

Domains, languages and variants

The base of the site sets the base URL, in Mara's case the German domain. Every language also has its own base. That can be a path, such as en with slashes before and after. It can also be a full URL.

Each language includes, among other things, these settings:

  • A title for the backend and the base of the language.
  • The locale, for example de_DE.UTF-8 or en_GB.UTF-8. It must be installed on the server.
  • The value for hreflang, which the SEO extension outputs for search engines. If it is missing, TYPO3 derives it from the locale.
  • A flag and how missing translations are handled, that is fallbackType and fallbacks.

The translations themselves are not in the site configuration. They live in the records of pages and content. How to translate is covered in the course “Mehrsprachigkeit und Übersetzungen”.

Locally, Mara does not work under the real domain. That is what baseVariants are for. Each variant has its own base and a condition, usually on the application context.

baseVariants:
  - base: 'https://lindenau.ddev.site/'
    condition: 'applicationContext == "Development"'
  - base: 'https://staging.musikschule-lindenau.de/'
    condition: 'applicationContext == "Production/Staging"'
YAML excerpt. In the application context Development, a local base URL of the ddev environment applies. In the context Production Staging, the address of the test server applies.

Error pages and static routes

Under errorHandling you define your own error pages. There is one entry per status code, such as 404 or 403. TYPO3 knows three kinds:

  • Page loads the content of a page. Usually that is an internal page, given as a TYPO3 link with the scheme t3 and the type page, followed by the page ID.
  • Fluid renders a Fluid template, for example from the sitepackage.
  • PHP calls your own PHP class.

The status code 0 catches all errors that are not listed individually.

errorHandling:
  - errorCode: 404
    errorHandler: Page
    errorContentSource: 't3://page?uid=8'
  - errorCode: 0
    errorHandler: Fluid
    errorFluidTemplate: 'EXT:lindenau_site/Resources/Private/Templates/Error.fluid.html'
YAML excerpt. For the error 404, the Page handler loads the page with the ID 8. For all other errors, code 0, the Fluid handler renders a template from the sitepackage lindenau_site.

Because error handling belongs to the site, it automatically depends on the current site and language. Someone who calls an English page gets the English 404 page. But it only reacts to HTTP errors such as 404 or 403. A PHP exception from a plugin goes to the general error and exception handling of TYPO3.

Static routes under routes answer a fixed path directly, without rendering a page. There are three types:

  • The type staticText delivers the text you entered. This way every site gets its own robots.txt without you creating a file.
  • The type uri delivers the content of a TYPO3 URL, that is a page, a file or an external address.
  • The type asset delivers a file from the folder Resources/Public of an extension. This works no matter where the extension lives in the project.
routes:
  - route: robots.txt
    type: staticText
    content: |
      User-agent: *
      Allow: /
      Sitemap: https://www.musikschule-lindenau.de/sitemap.xml
  - route: favicon.ico
    type: asset
    asset: 'EXT:lindenau_site/Resources/Public/Icons/favicon.ico'
YAML excerpt with two static routes. The first answers robots.txt with fixed text that allows all crawlers and names the sitemap. The second delivers the file favicon.ico from the public folder of the sitepackage under favicon.ico.

Redirects do not belong here. There is no route type for redirects. That is what the extension redirects is for.

Path of a request Real file in public? web server yes File no TYPO3 resolves the site Does a redirect match? EXT:redirects yes Redirect no Static route? routes yes Text, file no Page found? slug + enhancer yes Page no Nothing matches errorHandling 404 page
The first match answers. A real file always wins.

Page URLs with slugs

Routing for pages works without further settings, but it needs a site configuration. Every page has a slug. That is the readable part of its URL, such as kurse or ueber-uns. The slug is generated from the page title. It only contains characters that are allowed in a URL, and it is always lowercase.

You find the slug in the page properties in the field “URL Segment”. A button next to it generates it again from the title. A language prefix such as en is not part of the slug. It comes from the base of the language.

Every translation of a page has its own slug too. In Mara's site, the English version of the page kurse is called courses. This is how the English address of a course is built:

What a URL is made of www.musikschule-lindenau.de/en/courses/piano Domain www…lindenau.de base of the site config.yaml Language prefix /en base of the language languages Page slug /courses page properties URL segment Course /piano route enhancer + aspect routeEnhancers No query string left.
Each part of the URL comes from a different setting.

Route enhancers and aspects

Without further configuration, plugin parameters end up in the URL as a long query string, with plugin namespace, controller, action and ID. Route enhancers turn such parameters into readable path segments, such as news followed by the title of the article. The Core ships four types:

  • Simple maps simple parameters, for example a page number.
  • Plugin maps parameters with a plugin namespace.
  • Extbase knows the extension, the plugin, routes with controller and action, and default values.
  • PageType adds a suffix and maps it to a page type, for example html.

There is no separate enhancer for languages. The base of the language takes care of that.

Aspects transform values for the URL. The most important one is the PersistedAliasMapper. It replaces an ID with a value from the database, for example from the field path_segment or slug. The StaticValueMapper uses fixed mappings, the StaticRangeMapper allows a range of numbers, and the LocaleModifier translates fixed words per language.

For the course directory, Mara needs an enhancer of type Extbase with extension, plugin and routes, and an aspect that maps the course ID to the slug.

routeEnhancers:
  CourseDetail:
    type: Extbase
    limitToPages: [12]
    extension: Lindenau
    plugin: Courses
    routes:
      - routePath: '/{course_slug}'
        _controller: 'Course::show'
        _arguments:
          course_slug: course
    aspects:
      course_slug:
        type: PersistedAliasMapper
        tableName: tx_lindenau_domain_model_course
        routeFieldName: slug
YAML excerpt. The enhancer CourseDetail has the type Extbase and applies only on the page with the ID 12. It belongs to the extension Lindenau and the plugin Courses. The route has a placeholder course_slug and calls the action show of the Course controller. The placeholder is filled through the argument course. A PersistedAliasMapper reads the field slug of the course table for it.

The option limitToPages restricts an enhancer to certain page IDs, here to the course detail page. This avoids conflicts with other enhancers and speeds up resolving. Since TYPO3 14.2, an entry can also be an expression, for example a condition on the page type.

The PageType enhancer uses map to assign a suffix to a page type. That way it delivers a page with a certain type parameter under a fixed suffix. Examples are sitemap.xml for the sitemap, llms.txt or feed.xml.

routeEnhancers:
  PageTypeSuffix:
    type: PageType
    map:
      sitemap.xml: 1533906435
      feed.xml: 100
YAML excerpt. A PageType enhancer delivers the page type 1533906435 under the suffix sitemap.xml and the page type 100 under feed.xml.

Including routing from extensions: The file config.yaml can load further YAML files through imports. This way Mara pulls the routing configuration for news from her sitepackage instead of copying everything into the site.

imports:
  - { resource: 'EXT:lindenau_site/Configuration/Routing/News.yaml' }
The config.yaml imports the file News.yaml from the folder Routing of the sitepackage lindenau_site.

Since TYPO3 14.1 it is even easier. A site set can ship a file route-enhancers.yaml next to its config.yaml. It is merged into the site configuration automatically as soon as the site uses the set. The entries of the site itself always take precedence.

Redirects

The system extension redirects provides the module Sites > Link Management > Redirects. There you manage redirects. Each redirect is a record in the table sys_redirect, with source domain, source path, target and status code.

Status codes: The codes 301 and 308 mean a permanent redirect, 302 and 307 a temporary one. A new redirect uses 307 by default. This also applies to automatically created redirects, here through the site setting redirects.httpStatusCode.

Why not 301? Browsers and search engines remember permanent redirects. Afterwards the old URL is hardly usable any more, for example for a page of its own later. That is why the documentation advises against 301 for automatic redirects. For a real, planned move you choose 301 deliberately.

Slug changed: With the extension redirects installed, the site settings redirects.autoUpdateSlugs and redirects.autoCreateRedirects are active. When an editor changes the slug of a page with many subpages, this happens:

  1. TYPO3 updates the slugs of all subpages.
  2. For the page and every subpage, a redirect from the old to the new URL is created.
  3. A notification offers to revert the whole change or only the redirects.

Without the extension redirects, on the other hand, the old URL returns a 404 error after a slug change. In a workspace, no automatic redirects are created, only in the live workspace.

Source domain: If you enter an asterisk as the source domain, the redirect applies to all sites. If it should apply to one site only, you pick its domain.

Regular expressions: Mara wants to redirect all addresses under alt to matching paths under neu. She switches on “Is regular expression”, which is the field is_regexp in the record. The source path is then a regular expression with delimiters, for example two hash signs or two slashes. She inserts captured groups into the target with dollar 1, dollar 2 and so on. TYPO3 does not check the syntax and reports no errors, so you test the expression beforehand.

Source path: #^/alt/(.*)$#
Target:      /neu/$1
A redirect with a regular expression. The source path captures everything after alt slash as a group. The target is neu slash followed by the captured group, written as dollar 1.

Query parameters: Two options are easy to mix up here.

  • By default, the query parameters of the old URL are dropped. With keep_query_parameters, TYPO3 appends them to the target.
  • With respect_query_parameters, TYPO3 checks the parameters already while matching the source. A redirect for the path aktion with the parameter code equals abc then only applies when exactly this parameter comes along.
  • The option force_https enforces HTTPS for the target.
Two options, two places old URL /aktion?code=abc Redirect target /sommer?code=abc Entry: matching respect_query_parameters Parameters count when comparing with the source Exit: target keep_query_parameters Parameters are appended to the target Without keep, the parameters are dropped.
respect checks on the way in, keep passes on at the way out.

Cleaning up: After a relaunch, many redirects pile up. The hit counter, a feature toggle called redirects.hitCount, shows which ones are still used. It counts the calls. Afterwards the command redirects:cleanup removes old redirects by criteria such as age in days, hit count, domain, status code or path. The command leaves a redirect with the option protected alone. The option changes nothing about the redirect itself.

The second command, redirects:checkintegrity, checks for conflicts. One example is a loop where a points to b and b points back to a. Since a bugfix release of TYPO3 14.3, it also reports redirects that never apply because another one with the same source matches first.

vendor/bin/typo3 redirects:cleanup --days 90 --hitCount 1
vendor/bin/typo3 redirects:checkintegrity
Two commands. The first removes redirects that are older than 90 days and have fewer than one hit, so they were never called. The second checks all redirects for conflicts.

QR codes and short URLs

Since TYPO3 14, Link Management has the modules QR Codes and Short URLs next to Redirects. Both belong to the extension redirects and only work when it is installed. They store their entries as sys_redirect records with a type of their own. If the extension linkvalidator is installed, its module Check Links has also lived there since TYPO3 14.2.

QR Codes arrived with TYPO3 14.1. The QR code on Mara's concert poster contains a fixed URL. She can change the target behind it at any time, for example to the recordings after the concert, without reprinting the poster. The module offers the code as PNG or SVG in different sizes.

Short URLs arrived with TYPO3 14.2. A short URL is a redirect of type short_url with a simplified form. You type a short path yourself, or a button generates a random path of 8 characters. Each path may exist only once per domain, and TYPO3 rejects duplicates. After saving, the path and the domain can no longer be changed, but the target can.

The SEO extension

The system extension seo adds fields to the page properties, such as SEO title, description, details for social networks, noindex and canonical link. It outputs the matching meta tags. On top of that come three automatic outputs: the canonical link, the hreflang links and the XML sitemap.

Canonical link: It tells search engines the preferred URL of a page when the same content can be reached under several addresses. EXT:seo sets it automatically to the page itself. If an editor has pointed the field canonical_link to another page, that takes precedence. The canonical link then points to that other page.

config.disableCanonical = 1
config.disableHrefLang = 1
TypoScript. The first line switches off the automatic canonical output, the second the hreflang output.

hreflang: On multilingual sites, EXT:seo adds a hreflang link for every language version of a page. It only considers translations that actually exist and can be accessed. A site language without a translated page gets no link. If there are at least two such links, an entry with the value x-default is added. It points to the page in the default language. With config.disableHrefLang you switch the output off.

noindex: If a page is set to noindex in its SEO settings, EXT:seo creates neither a canonical link nor hreflang links for it. Such pages are also missing from the sitemap.

The XML sitemap

You activate the XML sitemap with the site set typo3/seo-sitemap. Mara has listed it in the dependencies of her site. The set ships the necessary TypoScript and, since TYPO3 14.1, also the route enhancers for the readable addresses. In the past you had to add these enhancers to every site configuration yourself.

  • At the address sitemap.xml directly after the domain you find the sitemap index. It points to the individual sitemaps.
  • The sitemap of the pages lives under the path sitemap-type, then pages, then sitemap.xml.
  • Every language has its sitemap under its own base. In Mara's site the English one is at en followed by sitemap.xml.

The sitemap is generated dynamically on every call. You do not have to rebuild it by hand after changes. You can adjust it through settings of the set:

  • The setting seo.sitemap.pages.excludedDoktypes filters by page type. By default it is set to 3, 4, 6, 7, 199 and 254. This leaves out links, shortcuts, backend user sections, mount points, spacers and folders.
  • The setting seo.sitemap.pages.excludePagesRecursive takes out pages together with all their subpages.
  • The setting seo.sitemap.pages.additionalWhere filters out pages with noindex and pages with their own canonical link by default.

Key points

  • The site configuration lives in config.yaml in the site's folder below config/sites and is edited in the module Sites > Setup.
  • Base URL, root page and languages belong in the site, reusable parts in a site set.
  • The root node is level 0 without an entry in pages. Only admins work there, with tables such as be_users, sys_file_storage and sys_filemounts.
  • The base of a language can be a path or a domain of its own.
  • Error handling: Page, Fluid or PHP per status code, and code 0 catches the rest.
  • Static routes: staticText, uri and asset. A real file in the folder public wins.
  • Route enhancers: Simple, Plugin, Extbase and PageType. Aspects such as the PersistedAliasMapper replace IDs with readable values.
  • Redirects are 307 by default. Slug changes create them automatically, except in a workspace.
  • keep_query_parameters passes parameters on, respect_query_parameters checks them while matching.
  • Since TYPO3 14, QR codes and short URLs are redirect records of the extension redirects.
  • EXT:seo sets canonical and hreflang automatically, except for noindex. The sitemap comes with the set typo3/seo-sitemap.

Terms

Site
A page tree with its own base URL, languages and configuration in a YAML file.
Root node
Level 0 above all pages with the ID 0, without its own entry in pages.
rootLevel
TCA option that defines whether a table is allowed on level 0, on pages or on both.
base
Base URL of a site or a language, as a path or a full URL.
Slug
Readable part of the URL of a page or a record.
Route enhancer
Rule that turns parameters of plugins or page types into readable path parts.
Aspect
Transformation of a value for the URL, for example from an ID to a slug.
Static route
Fixed path of the site that delivers text, a TYPO3 URL or a file.
Canonical link
The preferred URL of a page for search engines.
hreflang
Reference to the language versions of a page, with x-default for the default language.
Short URL
A short, fixed path stored as a redirect with a changeable target.

As of: November 15, 2026 (TYPO3 14.3 LTS)

Sources:

  • TYPO3 Explained 14.3, chapters Site Handling and Routing (Route Enhancements and Aspects, Static Routes)
  • Documentation of the system extensions redirects and seo 14.3
  • Changelog TYPO3 14.1 and 14.2 (route enhancers in site sets, sitemap set, QR Codes, Short URLs, limitToPages with expressions)
  • Source code TYPO3 14.3 (typo3/cms-core, cms-frontend, cms-redirects, cms-seo), checked for default values, status codes and middleware order
  • Learning objectives TYPO3 CMS Certified Integrator 14 LTS, course Sites, Routing and SEO

This study guide was written with AI and checked against the sources.

Certifications & exams

Which exam comes next?

You can already practise for 51 exams, and 16 are up for a vote. See all certifications with their official information, cast your vote or suggest your exam.

See all certifications