---
title: "Routing - readable, SEO-friendly URLs"
manual: "TYPO3 Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3coreapi:routing-introduction@main"
source: "ApiOverview/Routing/Index.rst"
modified: "2026-09-15T19:16:38+00:00"
---

# Routing - readable, SEO-friendly URLs

> [!NOTE]
> **New in version 14.1**
>
> Site sets can define route enhancers in a dedicated `route-enhancers.yaml`
> file.
>
> See [Feature: #107837 - Route enhancers in site sets](https://docs.typo3.org/c/typo3/cms-core/main/en-us/Changelog/14.1/Feature-107837-RouteEnhancersInSiteSets.html#feature-107837-1732800000)

When TYPO3 serves a request, it maps the incoming URL to a specific page or action,
for example, it maps an URL like `https://example.org/news` to a News page.
This process of determining the page and/or action to execute based on a specific
URL is called "Routing".

The input of a route is made up of several components. Some components can also be
split into further sub-components.

Routing also beautifies URI parameters, for example,
`https://example.org/profiles?user=magdalena` is converted into
`https://example.org/profiles/magdalena`

Routing is defined in the site configuration file [`config/sites/my_site/config.yaml`](../../Administration/DirectoryStructure/SiteFolder.md#file-site-config-sites-my-site-config-yaml)
or in a site set like `EXT:my_extension/Configuration/Sets/MySet/route-enhancers.yaml`.

Site-level route enhancer configuration always takes precedence over
set-defined enhancers. Route enhancers from site sets are merged in dependency
order.

**Table of contents**

-   [Key terminology](https://docs.typo3.org/permalink/t3coreapi:key-terminology@main)
-   [Routing in TYPO3](https://docs.typo3.org/permalink/t3coreapi:routing-in-typo3@main)
-   [Tips: using imports in YAML files](https://docs.typo3.org/permalink/t3coreapi:tips-using-imports-in-yaml-files@main)

**Subpages**

-   [Route Enhancements and Aspects](https://docs.typo3.org/permalink/t3coreapi:routing-advanced-routing-configuration@main)
-   [Extending](https://docs.typo3.org/permalink/t3coreapi:routing-extending-routing@main)
-   [Examples](https://docs.typo3.org/permalink/t3coreapi:routing-examples@main)

## Key terminology

Given a complex link (`URI`, `Uniform Resource Identificator`) like

```plaintext
https://subdomain.example.com:80/en/about-us/our-team/john-doe/publications/index.xhtml?utm_campaign=seo#start
```

all of its components can be broken down to:

| https:// | subdomain. | example. | com | :80 | /en | /about-us/our-team | /john-doe | /publications/ | index | .xhtml | ?utm_campaign= | seo | #start |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Protocol | Subdomain | Domain | TLD | Port | Site Language Prefix | Slug | Enhanced Route |  |  |  |
|  | Hostname |  |  |  | Route Enhancer | Route Decorator | Query string | argument value | Location Hash / Anchor |
|  | Route / Permalink |  |
| URL (no arguments, unlike the URI) |  |  |  |
| URI (everything) |

> [!TIP]
> **Hint**
>
> Please note that the following terminology is based on technical terms used in the TYPO3 Core,
> due to their class/object and interface names.

-   **Route**

    The "speaking URL" as a whole (without the domain parts); for example
    `/en/about-us/our-team/john-doe/publications/index.xhtml`.
    This is also sometimes referred to as `permalink`, some definitions also
    include the `Query string` for this term.

-   **Site Language Prefix**

    A global site language prefix (e.g. "/dk" or "/en-us") is not considered
    part of the slug, but rather a "prefix" to the slug.

-   **Slug**

    Unique name for a resource to use when creating URLs; for example the slug of the news detail page
    could be `/news/detail`, and
    the slug of a news record could be `2019-software-update`.

    Within TYPO3, a slug is always a part (section) of the URL "path" - it does not contain scheme, host, HTTP verb, etc.
    The URL "path" consists of one or more slugs which are concatenated into a single string.

    A slug is usually added to a TCA-based database table, containing rules for evaluation and definition.

    The default behaviour of a slug is as follows:

    -   A slug only contains characters which are allowed within URLs. Spaces,
        commas and other special characters are converted to a fallback character.
    -   A slug is always lower-cased.
    -   A slug is unicode-aware.
    -   Slugs must be separated by one or more character like "/", "-", "\_"
        and "&". Regular characters like letters should not be used as
        separators for better readability.

> [!NOTE]
> A slug of a record may contain slashes but this is not recommended:
> The risk of conflicts is higher when using slashes within slugs. For
> example, unrelated page hierarchies and records could have slugs
> forming the same URL path.

-   **Enhancers**

    Sections **after** a slug can be added ("enhancing" the route) both by "Route Enhancers" and also
    "(Route Enhancing) Decorators", see
    [Advanced routing configuration](https://docs.typo3.org/permalink/t3coreapi:routing-advanced-routing-configuration@main).

-   **Page Type Suffix**

    A Page Type Suffix indicates the type of a URL, usually ".html". It can also be left out completely.
    If set, it could control alternate variants of a URL, for example a RSS feed or a JSON representation.

    A Page Type Suffix is treated as an Enhancer, specifically a "(Route) Decorator".
    Other kinds of decorators could add additional parts to the route, but
    only after(!) the initial "Route Enhancer(s)".

-   **Enhanced Route**

    The combination of multiple Enhancers (and the Page Type Suffix) can be referred to as the "Enhanced Route".

-   **Query string**

    The main distinction of `URL` (Uniform Resource Locator) and `URI` (Uniform Resource Identifier) is that
    the URI also includes arguments/parameters and their values, beginning with a `?` and each argument
    separated by `&`, and the value separated from the argument name by `=`. This is commonly referred to as
    "Query string".

## Routing in TYPO3

Routing in TYPO3 is implemented based on the Symfony Routing components. It
consists of two parts:

-   [Page-based routing](https://docs.typo3.org/permalink/t3coreapi:routing-page-based-routing@main)
-   [Route Enhancements and Aspects](https://docs.typo3.org/permalink/t3coreapi:routing-advanced-routing-configuration@main)

Page Routing describes the process of resolving the concrete page (in earlier
TYPO3 versions this were the `id` and `L` `$_GET` parameters,
now this uses the Site Language Prefix plus one or more slugs),
whereas Route Enhancements and Aspects take care of all additionally configured
parameters (such as beautifying plugin parameters, handling `type` etc.).

### Page-based routing

TYPO3 provides built-in support for page-based routing, mapping pages to
routes automatically.

Page-based routing is always enabled in TYPO3 and requires a site
configuration (see [Site handling](https://docs.typo3.org/permalink/t3coreapi:sitehandling@main)) for your website. Each page's route
is determined by its `slug` field, which can be viewed in the page
properties.

> [!TIP]
> **Hint**
>
> Ensure that editors have the necessary permissions to modify the `slug`
> field if they need to change or update slugs when modifying page titles.

The generation of page slugs is controlled via the TCA configuration of the
`pages` table (`slug` field). This configuration can be customized in your
extension’s `TCA/Overrides/pages.php`. Refer to the TCA reference
([Slugs / URL parts](https://docs.typo3.org/m/typo3/reference-tca/main/en-us/ColumnsConfig/Type/Slug/Index.html#columns-slug)) for available options.

If the system extension [`typo3/cms-redirects`](https://packagist.org/packages/typo3/cms-redirects) is installed,
redirects are automatically generated when a slug is adjusted by and editor.

## Tips: using imports in YAML files

> [!NOTE]
> **New in version 14.1**
>
> Site sets can define route enhancers in a dedicated `route-enhancers.yaml`
> file. You can also set up imports in the yaml file (see below).
>
> See [Feature: #107837 - Route enhancers in site sets](https://docs.typo3.org/c/typo3/cms-core/main/en-us/Changelog/14.1/Feature-107837-RouteEnhancersInSiteSets.html#feature-107837-1732800000)

As routing configuration (and site configuration in general) can get pretty long
fast, you should make use of imports in your YAML configuration which allows you
to add routing configurations from different files and different extensions.

Example:

**EXT:my_extension/Configuration/Sets/MySet/route-enhancers.yaml**

```yaml
imports:
  - { resource: 'route-enhancers/*.yaml' }
```