Lernseite · Sites, Routing und SEO
Sites, Routing und SEO: Vom Seitenbaum zur sauberen Adresse
Eine Website braucht eine Adresse, Sprachen, Fehlerseiten, lesbare URLs, Weiterleitungen und Angaben für Suchmaschinen. Auf dieser Seite begleitest du die Integratorin Mara beim Relaunch der Musikschule Lindenau. Danach weißt du, was in die Site-Konfiguration gehört, wie TYPO3 eine URL auflöst, wie Redirects arbeiten und was die SEO-Extension von selbst erledigt.
Das Beispiel: die Musikschule Lindenau
Das Projekt ist ein Composer-Projekt mit TYPO3 14.3. Maras Sitepackage heißt lindenau_site, das Composer-Paket dazu lindenau/site. Die alte Website hatte Adressen wie index.php mit einer Seiten-ID als Parameter. Die neue soll lesbare Adressen haben, etwa kurse und dann klavier.
Die deutsche Website läuft unter www.musikschule-lindenau.de, die englische Fassung unter dem Pfad en. Für das Kursverzeichnis hat das Team ein kleines Extbase-Plugin, für Neuigkeiten die Extension news.
Die Site-Konfiguration
Eine Site ist in TYPO3 ein Seitenbaum mit eigener Adresse. Ihre Einstellungen bearbeitest du im Backend-Modul Sites > Setup. Dort legst du Sites an, bearbeitest Basis-URL, Sprachen, Fehlerbehandlung und statische Routen und wählst die Site Sets aus.
Das Formular schreibt nicht in die Datenbank, sondern in eine Datei. Jede Site hat einen Ordner unter config/sites, benannt nach ihrer Kennung. Darin liegt die Datei config.yaml, bei Maras Site mit der Kennung lindenau also im Ordner config/sites/lindenau. Daneben können weitere Dateien liegen, etwa settings.yaml für die Site Settings oder csp.yaml für die Content Security Policy. Der Ordner gehört in die Versionskontrolle.
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: strictDie wichtigsten Schlüssel:
- Der Schlüssel
rootPageIdnennt die Startseite der Site. - Der Schlüssel
baseist die Basis-URL, also der Einstiegspunkt der Site. - Unter
languagesstehen die Sprachen, untererrorHandlingdie Fehlerseiten und unterroutesdie statischen Routen. - Unter
routeEnhancerssteht das Routing für Extensions, unterdependenciesdie Site Sets.
Auf der Kommandozeile zeigt der Befehl site:show mit der Kennung die komplette Konfiguration einer Site, samt der eingebundenen Sets. Der Befehl site:list listet alle Sites, site:sets:list alle verfügbaren Sets.
vendor/bin/typo3 site:show lindenau
vendor/bin/typo3 site:list
vendor/bin/typo3 site:sets:listSite oder Site Set? Ein Site Set liefert den wiederverwendbaren Teil, zum Beispiel TypoScript für alle Sites eines Designs und Standardwerte von Settings. Was nur zu dieser einen Website gehört, steht in der Site-Konfiguration: die Basis-URL, die Startseite mit ihrer rootPageId und die Sprachen.
Root Node und Startseite
Ganz oben im Seitenbaum steht der Root Node, dargestellt mit einer Weltkugel. Er ist die Ebene 0 über allen Seiten und hat die ID 0. Er ist keine Seite und hat keinen Eintrag in der Tabelle pages.
Auf dem Root Node liegen nur Datensätze, die für die ganze Installation gelten. Ob eine Tabelle dort erlaubt ist, steuert die TCA-Option rootLevel:
- Mit dem Wert 1 sind Datensätze nur auf Ebene 0 erlaubt. Das gilt für Backend-Benutzer und Backend-Gruppen, für Dateispeicher in der Tabelle
sys_file_storageund für Dateifreigaben in der Tabellesys_filemounts. - Mit dem Wert minus 1 sind sie auf Ebene 0 und auf Seiten erlaubt. Das gilt zum Beispiel für Kategorien und Redirects.
- Mit dem Wert 0, dem Normalfall, gehören Datensätze nur auf Seiten oder in Ordner. Inhaltselemente und Frontend-Benutzer liegen deshalb nie auf dem Root Node.
Auf Ebene 0 dürfen nur Administratoren arbeiten, und auch sie nur mit Tabellen, deren TCA das erlaubt.
Davon zu unterscheiden ist die Startseite einer Site. Sie ist eine ganz normale Seite. Sie liegt direkt unter dem Root Node, hat also die pid 0, oder sie trägt die Eigenschaft „Use as Root Page“. Ihre UID ist eine gewöhnliche Zahl, bei Mara die 1. Legst du im Backend eine neue Seite auf Ebene 0 an, erzeugt TYPO3 gleich eine einfache Site-Konfiguration dazu.
Domains, Sprachen und Varianten
Die base der Site legt die Basis-URL fest, bei Mara die deutsche Domain. Jede Sprache hat zusätzlich ihre eigene base. Das kann ein Pfad sein, etwa en mit Schrägstrichen davor und danach. Es kann aber auch eine vollständige URL sein.
Zu jeder Sprache gehören unter anderem diese Angaben:
- Ein Titel für das Backend und die
baseder Sprache. - Die locale, etwa de_DE.UTF-8 oder en_GB.UTF-8. Sie muss auf dem Server installiert sein.
- Der Wert für hreflang, den die SEO-Extension für Suchmaschinen ausgibt. Fehlt er, leitet TYPO3 ihn aus der locale ab.
- Eine Flagge und der Umgang mit fehlenden Übersetzungen, also
fallbackTypeundfallbacks.
Die Übersetzungen selbst stehen nicht in der Site-Konfiguration. Sie liegen in den Datensätzen der Seiten und Inhalte. Wie man übersetzt, zeigt der Kurs „Mehrsprachigkeit und Übersetzungen“.
Lokal arbeitet Mara nicht unter der echten Domain. Dafür gibt es baseVariants. Jede Variante hat eine eigene base und eine Bedingung, meist auf den Application Context.
baseVariants:
- base: 'https://lindenau.ddev.site/'
condition: 'applicationContext == "Development"'
- base: 'https://staging.musikschule-lindenau.de/'
condition: 'applicationContext == "Production/Staging"'Fehlerseiten und statische Routen
Unter errorHandling legst du eigene Fehlerseiten fest. Je Statuscode, etwa 404 oder 403, gibt es einen Eintrag. TYPO3 kennt drei Arten:
- Page lädt den Inhalt einer Seite. Meist ist das eine interne Seite, angegeben als TYPO3-Link mit dem Schema t3 und dem Typ page, gefolgt von der Seiten-ID.
- Fluid rendert ein Fluid-Template, etwa aus dem Sitepackage.
- PHP ruft eine eigene PHP-Klasse auf.
Der Statuscode 0 fängt alle Fehler ab, die nicht einzeln aufgeführt sind.
errorHandling:
- errorCode: 404
errorHandler: Page
errorContentSource: 't3://page?uid=8'
- errorCode: 0
errorHandler: Fluid
errorFluidTemplate: 'EXT:lindenau_site/Resources/Private/Templates/Error.fluid.html'Weil die Fehlerbehandlung zur Site gehört, hängt sie automatisch von der aktuellen Site und Sprache ab. Wer die englische Seite aufruft, bekommt die englische 404-Seite. Sie reagiert aber nur auf HTTP-Fehler wie 404 oder 403. Eine PHP-Exception aus einem Plugin landet in der allgemeinen Fehler- und Ausnahmebehandlung von TYPO3.
Statische Routen unter routes antworten direkt auf einen festen Pfad, ohne eine Seite zu rendern. Es gibt drei Typen:
- Der Typ staticText liefert den eingetragenen Text aus. So bekommt jede Site ihre eigene robots.txt, ohne dass du eine Datei anlegst.
- Der Typ uri liefert den Inhalt einer TYPO3-URL aus, also einer Seite, einer Datei oder einer externen Adresse.
- Der Typ asset liefert eine Datei aus dem Ordner
Resources/Publiceiner Extension aus. Das klappt unabhängig davon, wo die Extension im Projekt liegt.
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'Weiterleitungen gehören nicht hierher. Einen Routen-Typ für Redirects gibt es nicht, dafür ist die Extension redirects da.
Seiten-URLs mit Slugs
Das Routing für Seiten funktioniert ohne weitere Einstellungen, braucht aber eine Site-Konfiguration. Jede Seite hat einen Slug. Das ist der lesbare Teil ihrer URL, etwa kurse oder ueber-uns. Der Slug wird aus dem Seitentitel erzeugt. Er enthält nur Zeichen, die in einer URL erlaubt sind, und ist immer kleingeschrieben.
Den Slug findest du in den Seiteneigenschaften im Feld „URL Segment“. Ein Knopf daneben erzeugt ihn neu aus dem Titel. Ein Sprach-Präfix wie en gehört nicht zum Slug. Er kommt aus der base der Sprache.
Auch jede Übersetzung einer Seite hat ihren eigenen Slug. Die englische Fassung der Seite kurse heißt bei Mara courses. So setzt sich die englische Adresse eines Kurses zusammen:
Route Enhancer und Aspects
Ohne weitere Konfiguration landen Plugin-Parameter als langer Query-String in der URL, mit Plugin-Namensraum, Controller, Action und ID. Route Enhancer bilden solche Parameter als lesbare Pfadsegmente ab, etwa news und dann der Titel des Artikels. Der Core bringt vier Typen mit:
- Simple bildet einfache Parameter ab, zum Beispiel eine Seitenzahl.
- Plugin bildet Parameter mit einem Plugin-Namensraum ab.
- Extbase kennt Extension, Plugin, Routen mit Controller und Action sowie Standardwerte.
- PageType hängt eine Endung an und ordnet sie einem Seitentyp zu, zum Beispiel html.
Einen eigenen Enhancer für Sprachen gibt es nicht. Dafür sorgt die base der Sprache.
Aspects wandeln Werte für die URL um. Der wichtigste ist der PersistedAliasMapper. Er ersetzt eine ID durch einen Wert aus der Datenbank, etwa aus dem Feld path_segment oder slug. Der StaticValueMapper nutzt feste Zuordnungen, der StaticRangeMapper erlaubt einen Zahlenbereich, und der LocaleModifier übersetzt feste Wörter je Sprache.
Für das Kursverzeichnis braucht Mara einen Enhancer vom Typ Extbase mit Extension, Plugin und Routen und einen Aspect, der die Kurs-ID auf den Slug abbildet.
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: slugDie Option limitToPages beschränkt einen Enhancer auf bestimmte Seiten-IDs, hier auf die Kurs-Detailseite. Das vermeidet Konflikte mit anderen Enhancern und beschleunigt die Auflösung. Seit TYPO3 14.2 darf ein Eintrag auch ein Ausdruck sein, etwa eine Bedingung auf den Seitentyp.
Der PageType-Enhancer ordnet über map eine Endung einem Seitentyp zu. So liefert er eine Seite mit einem bestimmten type-Parameter unter einer festen Endung aus. Beispiele sind sitemap.xml für die Sitemap, llms.txt oder feed.xml.
routeEnhancers:
PageTypeSuffix:
type: PageType
map:
sitemap.xml: 1533906435
feed.xml: 100Routing aus Extensions einbinden: Die Datei config.yaml kann weitere YAML-Dateien über imports laden. So holt Mara die Routing-Konfiguration für news aus ihrem Sitepackage, statt alles in die Site zu kopieren.
imports:
- { resource: 'EXT:lindenau_site/Configuration/Routing/News.yaml' }Seit TYPO3 14.1 geht es noch einfacher. Ein Site Set kann eine Datei route-enhancers.yaml neben seiner config.yaml mitbringen. Sie wird automatisch in die Site-Konfiguration eingemischt, sobald die Site das Set nutzt. Die Einträge der Site selbst haben dabei immer Vorrang.
Weiterleitungen
Die System-Extension redirects bringt das Modul Sites > Link Management > Redirects. Dort verwaltest du Weiterleitungen. Jeder Redirect ist ein Datensatz in der Tabelle sys_redirect, mit Quell-Domain, Quellpfad, Ziel und Statuscode.
Statuscodes: Die Codes 301 und 308 bedeuten eine dauerhafte Weiterleitung, 302 und 307 eine vorübergehende. Ein neuer Redirect nutzt standardmäßig 307. Das gilt auch für automatisch erzeugte Weiterleitungen, hier über das Site-Setting redirects.httpStatusCode.
Warum nicht 301? Browser und Suchmaschinen merken sich dauerhafte Weiterleitungen. Die alte URL bleibt danach kaum noch nutzbar, etwa für eine spätere eigene Seite. Darum rät die Dokumentation für automatische Redirects von 301 ab. Für einen echten, geplanten Umzug wählst du 301 bewusst.
Slug geändert: Mit installierter Extension redirects sind die Site-Settings redirects.autoUpdateSlugs und redirects.autoCreateRedirects aktiv. Ändert ein Redakteur den Slug einer Seite mit vielen Unterseiten, passiert Folgendes:
- TYPO3 passt die Slugs aller Unterseiten an.
- Für die Seite und jede Unterseite entsteht ein Redirect von der alten auf die neue URL.
- Eine Meldung bietet an, die ganze Änderung oder nur die Redirects zurückzunehmen.
Ohne die Extension redirects liefert die alte URL nach einer Slug-Änderung dagegen einen 404-Fehler. In einem Workspace entstehen keine automatischen Redirects, nur im Live-Workspace.
Quell-Domain: Trägst du als Quell-Domain ein Sternchen ein, gilt der Redirect für alle Sites. Soll er nur für eine Site gelten, wählst du ihre Domain.
Reguläre Ausdrücke: Mara will alle Adressen unter alt auf passende Pfade unter neu umleiten. Dazu aktiviert sie „Is regular expression“, im Datensatz das Feld is_regexp. Der Quellpfad ist dann ein regulärer Ausdruck mit Begrenzern, etwa zwei Rauten oder zwei Schrägstrichen. Gefundene Gruppen setzt sie im Ziel mit Dollar 1, Dollar 2 und so weiter ein. TYPO3 prüft die Syntax nicht und meldet keine Fehler, deshalb testet man den Ausdruck vorher.
Quellpfad: #^/alt/(.*)$#
Ziel: /neu/$1Query-Parameter: Hier verwechselt man leicht zwei Optionen.
- Standardmäßig fallen Query-Parameter der alten URL weg. Mit keep_query_parameters hängt TYPO3 sie an das Ziel an.
- Mit respect_query_parameters prüft TYPO3 die Parameter schon beim Abgleich der Quelle. Ein Redirect für den Pfad aktion mit dem Parameter code gleich abc greift dann nur, wenn genau dieser Parameter mitkommt.
- Die Option force_https erzwingt HTTPS für das Ziel.
Aufräumen: Nach einem Relaunch sammeln sich viele Redirects an. Welche noch genutzt werden, zeigt der Hit Counter, ein Feature Toggle namens redirects.hitCount. Er zählt die Aufrufe. Danach entfernt der Befehl redirects:cleanup alte Redirects nach Kriterien wie Alter in Tagen, Trefferzahl, Domain, Statuscode oder Pfad. Einen Redirect mit der Option protected lässt der Befehl in Ruhe. Die Option ändert nichts an der Weiterleitung selbst.
Der zweite Befehl, redirects:checkintegrity, prüft auf Konflikte. Ein Beispiel ist eine Schleife, bei der a auf b und b wieder auf a zeigt. Seit einem Bugfix-Release von TYPO3 14.3 meldet er auch Redirects, die nie greifen, weil ein anderer mit gleicher Quelle vorher passt.
vendor/bin/typo3 redirects:cleanup --days 90 --hitCount 1
vendor/bin/typo3 redirects:checkintegrityQR Codes und Short URLs
Seit TYPO3 14 stehen unter Link Management neben Redirects die Module QR Codes und Short URLs. Beide gehören zur Extension redirects und funktionieren nur, wenn sie installiert ist. Sie speichern ihre Einträge als sys_redirect-Datensätze mit eigenem Typ. Ist die Extension linkvalidator installiert, liegt seit TYPO3 14.2 auch ihr Modul Check Links dort.
QR Codes kamen mit TYPO3 14.1. Der QR-Code auf Maras Konzertplakat enthält eine feste URL. Das Ziel dahinter kann sie jederzeit ändern, etwa nach dem Konzert auf die Aufnahmen, ohne das Plakat neu zu drucken. Das Modul bietet den Code als PNG oder SVG in verschiedenen Größen an.
Short URLs kamen mit TYPO3 14.2. Eine Short URL ist ein Redirect vom Typ short_url mit vereinfachtem Formular. Du tippst einen kurzen Pfad selbst ein, oder ein Knopf erzeugt einen zufälligen Pfad aus 8 Zeichen. Je Domain darf es jeden Pfad nur einmal geben, doppelte Pfade lehnt TYPO3 ab. Nach dem Speichern lassen sich Pfad und Domain nicht mehr ändern, das Ziel schon.
Die SEO-Extension
Die System-Extension seo ergänzt die Seiteneigenschaften um Felder wie SEO-Titel, Beschreibung, Angaben für soziale Netzwerke, noindex und Canonical-Link. Sie gibt die passenden Meta-Tags aus. Dazu kommen drei automatische Ausgaben: der Canonical-Link, die hreflang-Links und die XML-Sitemap.
Canonical-Link: Er nennt Suchmaschinen die bevorzugte URL einer Seite, wenn dieselben Inhalte unter mehreren Adressen erreichbar sind. EXT:seo setzt ihn automatisch auf die Seite selbst. Hat ein Redakteur im Feld canonical_link auf eine andere Seite verwiesen, hat das Vorrang. Dann zeigt der Canonical-Link auf diese andere Seite.
config.disableCanonical = 1
config.disableHrefLang = 1hreflang: Bei mehrsprachigen Sites fügt EXT:seo für jede Sprachfassung einer Seite einen hreflang-Link ein. Berücksichtigt werden nur Übersetzungen, die es wirklich gibt und die aufrufbar sind. Eine Sprache der Site ohne übersetzte Seite bekommt keinen Link. Gibt es mindestens zwei solche Links, kommt ein Eintrag mit dem Wert x-default dazu. Er zeigt auf die Seite in der Standardsprache. Mit config.disableHrefLang schaltest du die Ausgabe ab.
noindex: Steht eine Seite in ihren SEO-Einstellungen auf noindex, erzeugt EXT:seo für sie weder Canonical-Link noch hreflang-Links. Solche Seiten fehlen außerdem in der Sitemap.
Die XML-Sitemap
Die XML-Sitemap aktivierst du mit dem Site Set typo3/seo-sitemap. Mara hat es bei ihrer Site unter den Abhängigkeiten eingetragen. Das Set bringt das nötige TypoScript mit und seit TYPO3 14.1 auch die Route Enhancer für die lesbaren Adressen. Früher musste man diese Enhancer in jede Site-Konfiguration selbst eintragen.
- Unter der Adresse sitemap.xml direkt hinter der Domain liegt der Sitemap-Index. Er verweist auf die einzelnen Sitemaps.
- Die Sitemap der Seiten liegt unter dem Pfad sitemap-type, dann pages, dann sitemap.xml.
- Jede Sprache hat ihre Sitemap unter ihrer eigenen
base. Die englische liegt bei Mara unter en und dann sitemap.xml.
Die Sitemap wird bei jedem Aufruf dynamisch erzeugt. Du musst sie nach Änderungen nicht von Hand neu bauen. Anpassen lässt sie sich über Settings des Sets:
- Das Setting
seo.sitemap.pages.excludedDoktypesfiltert nach Seitentyp. Standardmäßig steht es auf 3, 4, 6, 7, 199 und 254. Damit fehlen Links, Shortcuts, Backend-Benutzer-Bereiche, Mount Points, Trenner und Ordner. - Das Setting
seo.sitemap.pages.excludePagesRecursivenimmt Seiten samt allen Unterseiten heraus. - Das Setting
seo.sitemap.pages.additionalWherefiltert standardmäßig Seiten mit noindex und Seiten mit eigenem Canonical-Link heraus.
Das Wichtigste in Kürze
- Die Site-Konfiguration liegt in
config.yamlim Ordner der Site unterconfig/sitesund wird im Modul Sites > Setup bearbeitet. - Basis-URL, Startseite und Sprachen gehören in die Site, Wiederverwendbares in ein Site Set.
- Der Root Node ist Ebene 0 ohne Eintrag in pages. Dort arbeiten nur Admins, mit Tabellen wie be_users, sys_file_storage und sys_filemounts.
- Die
baseeiner Sprache kann ein Pfad oder eine eigene Domain sein. - Fehlerbehandlung: Page, Fluid oder PHP je Statuscode, der Code 0 fängt den Rest.
- Statische Routen: staticText, uri und asset. Eine echte Datei im Ordner public gewinnt.
- Route Enhancer: Simple, Plugin, Extbase und PageType. Aspects wie der PersistedAliasMapper ersetzen IDs durch lesbare Werte.
- Redirects sind standardmäßig 307. Slug-Änderungen erzeugen sie automatisch, nur nicht im Workspace.
- keep_query_parameters gibt Parameter weiter, respect_query_parameters prüft sie beim Abgleich.
- QR Codes und Short URLs sind seit TYPO3 14 Redirect-Datensätze der Extension redirects.
- EXT:seo setzt Canonical und hreflang automatisch, außer bei noindex. Die Sitemap kommt mit dem Set typo3/seo-sitemap.
Begriffe
- Site
- Seitenbaum mit eigener Basis-URL, Sprachen und Konfiguration in einer YAML-Datei.
- Root Node
- Ebene 0 über allen Seiten mit der ID 0, ohne eigenen Eintrag in pages.
- rootLevel
- TCA-Option, die festlegt, ob eine Tabelle auf Ebene 0, auf Seiten oder auf beiden erlaubt ist.
- base
- Basis-URL einer Site oder einer Sprache, als Pfad oder vollständige URL.
- Slug
- Lesbarer Teil der URL einer Seite oder eines Datensatzes.
- Route Enhancer
- Regel, die Parameter von Plugins oder Seitentypen als lesbare Pfadteile abbildet.
- Aspect
- Umwandlung eines Werts für die URL, etwa von einer ID zu einem Slug.
- Statische Route
- Fester Pfad der Site, der Text, eine TYPO3-URL oder eine Datei ausliefert.
- Canonical-Link
- Angabe der bevorzugten URL einer Seite für Suchmaschinen.
- hreflang
- Verweis auf die Sprachfassungen einer Seite, mit x-default für die Standardsprache.
- Short URL
- Kurzer, fester Pfad als Redirect mit änderbarem Ziel.