Study guide · Sites, Routing and SEO
Sites, routing and SEO: From the page tree to a clean address
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: strictThe most important keys:
- The key
rootPageIdnames the root page of the site. - The key
baseis the base URL, the entry point of the site. - Under
languagesyou find the languages, undererrorHandlingthe error pages and underroutesthe static routes. - Under
routeEnhancersyou find the routing for extensions, and underdependenciesthe 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:listSite 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 tablesys_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
baseof 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
fallbackTypeandfallbacks.
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"'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'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/Publicof 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'Redirects do not belong here. There is no route type for redirects. That is what the extension redirects is for.
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:
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: slugThe 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: 100Including 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' }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:
- TYPO3 updates the slugs of all subpages.
- For the page and every subpage, a redirect from the old to the new URL is created.
- 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/$1Query 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.
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:checkintegrityQR 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 = 1hreflang: 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.excludedDoktypesfilters 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.excludePagesRecursivetakes out pages together with all their subpages. - The setting
seo.sitemap.pages.additionalWherefilters out pages with noindex and pages with their own canonical link by default.
Key points
- The site configuration lives in
config.yamlin the site's folder belowconfig/sitesand 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
baseof 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.