Menus and Path Aliases

The Standard profile creates five menus. A Minimal install creates only the Administration and User account menus that the toolbar needs; menus are configuration, so a site that starts from a recipe or a site template receives the menus that recipe defines.

The Drupal User Guide states that a menu link is shown only to visitors who have access to the page it points to, and that a menu is displayed by placing its block in a region. The guide’s menu concept page was last updated on 2025-04-14 and still names the Bartik theme; in current Drupal the front-end theme is Olivero (which leaves core in Drupal 12), and the Standard profile no longer creates the Article and Page content types since 11.4, so a tutorial that adds "the About page" to the menu must first create a content type.

To add a menu, open Structure > Menus > Add menu and give it a label, a machine name (meridian-visit is fine; the machine name is immutable) and a description. The menu is a system.menu.<name> configuration object, so it travels through configuration management (see Configuration Management). Its links, if they are content links, are content: they are not in the configuration export, so a link created on production does not appear after a configuration import on another environment. Static links, by contrast, always exist wherever the module is installed.

There are three ways for an editor to create a content link:

The "Show as expanded" box matters to themes: the menu block shows the children of an expanded link even if the link is not in the active trail, and the Olivero main menu uses it to decide which submenus open on hover. Unchecking "Enabled" hides the link without deleting it.

The "Menu settings" box on the content form is controlled per content type under Structure > Content types > Exhibition > Edit > Menu settings: the available menus (checkboxes) and the default parent item. They are stored as third-party settings of the content type, a schema defined by Menu UI (available_menus, a list of menu machine names, and parent, a string such as main:).

Source: Drupal User Guide: Adding a Page to the Navigation

The default parent is written as <menu machine name>:<plugin ID of the parent link>, so main: alone means the top level of the main menu. If the parent plugin ID no longer exists (a static link was renamed, a content link was deleted), the form silently falls back to the top level; keep the string in step with the links you actually have.

Structure > Menus > Edit menu lists the links as a drag-and-drop tree. Dragging a row changes its weight and parent; "Show row weights" exposes the numbers (lower weights first) for keyboard and assistive technology users, as described in the User Guide page on changing the order of navigation. Sorting is by weight, then title, then plugin ID. Internally the tree manipulator builds a key from the weight (offset so that negative and positive weights sort alike), the translated title and the plugin ID, which is why two links with the same weight appear in alphabetical order, in the language of the current page.

Keep menus shallow. Two levels cover most museum sites, and the Menu system’s maximum depth is limited by the storage (MenuLinkTree::maxDepth() returns the storage limit, nine levels in the default menu_tree table), which a deep Exhibitions hierarchy should never approach.

The front page is not a menu item but a setting: Configuration > System > Basic site settings (/admin/config/system/site-information) has a "Front page" field that takes a path (/home, /node/1 or an alias), exactly as the User Guide describes. The same screen sets the default 403 and 404 pages. All three are stored in system.site (page.front, page.403, page.404), and the form stores the system path even when you type an alias, so the setting survives later alias changes. The <front> route in a menu link always resolves to the configured value.

The block renders the menu through the menu.html.twig theme hook, with suggestions per menu (menu--main.html.twig, menu--footer.html.twig); override them in the theme as described in Template Suggestions and Preprocess. The variable items holds the links with title, url, below, in_active_trail, is_expanded and attributes.

Source: Twig in Drupal

The {% import _self as menus %} line is a leftover from the Starterkit menu.html.twig recursion macro and can be removed from a flat menu. The link() function renders an anchor with the cacheability of the URL object; printing item.url as a string instead loses the access and cache metadata, which is the commonest cause of a link that is shown to the wrong audience.

A module offers links in MODULE.links.menu.yml. The keys are title (required), description, route_name (or url for an external link, which must be fully qualified), route_parameters, parent (the plugin ID of another link), weight, menu_name (the target menu; it defaults to tools), enabled (1 or 0) and options (as for Url::fromRoute()).

Source: Providing module-defined menu links

Menu links are discovered into the menu_tree table; after adding or changing a links.menu.yml file, rebuild caches (drush cache:rebuild) so that the definition is rediscovered. A route name that does not exist raises a routing error when the link is rendered, not when it is discovered. The alter hook is hook_menu_links_discovered_alter(); there is no hook that adds a single link, and dynamic links belong in a deriver class, or in a call to addDefinition() on the plugin.manager.menu.link service, which requires a provider key. In Drupal 11.1 and later the alter hook is implemented as a method with the Hook attribute on a class in src/Hook, as covered in Hooks and Object-Oriented Hooks; books written for Drupal 10 show it as a function in the .module file, which still works through #[LegacyHook] compatibility but is no longer the recommended style.

Source: Providing module-defined menu links

A content link is a normal content entity, so an update hook, a post-update function or a migration can create them. The link field takes an internal: URI for a path, an entity:node/ID URI that survives alias changes, or an external URL.

Source: MenuLinkContent class

Prefer entity:node/12 over internal:/exhibitions/dinosaur-hall for links to content: the entity: form is resolved to the current alias on every render, so a Pathauto regeneration never leaves a menu link pointing to a retired alias.

The menu tree service (menu.link_tree, Drupal\Core\Menu\MenuLinkTreeInterface) loads, transforms and renders menu trees. The three steps are always the same: load a tree with MenuTreeParameters, run it through manipulators, build the render array.

Source: MenuLinkTree class

checkNodeAccess runs a single entity query for every node link in the tree and should run before checkAccess, which replaces inaccessible links with placeholder objects and empties their subtrees so that the result can be cached. flatten turns a tree into a single level. Omitting the access manipulator is a security defect: the menu would then list links to unpublished or restricted pages. build() adds the config:system.menu.<name> cache tag. The service is registered with autowiring aliases, so a class in src can request MenuLinkTreeInterface by type (see Services and Dependency Injection).

A preprocess function or an OOP hook for the menu theme hook adds classes or attributes to every item; themes can implement hooks as classes from Drupal 11.3 and preprocess hooks from 11.2. Details are in Template Suggestions and Preprocess.

The User Guide defines the path as the part of the URL that identifies a function or a content item (node/7) and an alias as a readable replacement shown instead (/AboutUs). Aliases are stored as path_alias content entities, which Drupal has used since 8.8 instead of the old url_alias table. A path_alias has a path (the system path, which must start with a slash), an alias (which must start with a slash; whitespace and trailing slashes are trimmed on save), a langcode (default "Not specified", which applies to every language) and a status. It is revisionable, with the base table path_alias and the revision table path_alias_revision, and a constraint rejects a second alias that duplicates the same alias in the same language.

An alias is a second name, not a rename. The system path keeps working: /node/12 and /exhibitions/dinosaur-hall serve the same page unless the Redirect module’s route normalisation is on, which redirects the former to the latter. That duplication is the SEO reason for the Redirect module below.

With the Path module enabled, content, taxonomy term and user forms have a "URL alias" box, and the list of all aliases, filtered by alias, is at Configuration > Search and metadata > URL aliases (/admin/config/search/path). An editor needs create url aliases to set an alias on content; administer url aliases is needed for the list screen and for aliases that point at any path, not only at the entity being edited.

Rules the form enforces: the alias starts with a slash (a missing slash is a validation error), is unique per language, and the system path must exist and be accessible to the person who saves ("Either the path …​ is invalid or you do not have access to it"). Alias matching ignores letter case, so /About and /about are the same alias.

Two path processors do the work. On the way in, path_alias.path_processor (AliasPathProcessor, inbound priority 100) asks the alias manager for the system path that belongs to the requested alias, in the current language and then in "Not specified"; the router then sees /node/12. On the way out, the same service (outbound priority 300) asks for the alias of every system path that code turns into a URL, so Url::fromRoute('entity.node.canonical', ['node' => 12])->toString() returns the alias. The manager (path_alias.manager) caches results per language in cache.data, and the repository (path_alias.repository) is the only class that reads the table. The older path_alias.whitelist service, which kept the list of path prefixes that have aliases so that most requests skip the database, is deprecated since Drupal 11.1 and removed in 12.0; the prefix-list services replace it, so code that injected it must be updated.

Because aliases are resolved before routing, an alias can shadow a real route. An administrator with administer url aliases who creates the alias /user/login for another page replaces the login form for every visitor. Treat the permission as sensitive, never give it to the Content Editor role, and review the alias list when a site behaves oddly at a well-known address. The same mechanism explains why a Pathauto pattern must never produce /admin, /user or other reserved first segments.

Source: PathAlias class

The \Drupal::service() call is acceptable in a script or a test; in a class, inject AliasManagerInterface. Saving and deleting an alias clears the alias manager cache for the affected paths. PathAlias::create() is also what a Migrate destination uses, so a CSV import of the collection can write aliases with the objects.

An alias belongs to one language or to "Not specified". Meridian’s Spanish site uses /es/exposiciones/sala-dinosaurios: the /es prefix is added by the language negotiation, not stored in the alias, and the alias /exposiciones/sala-dinosaurios has the langcode es. Pathauto creates one alias per translation when the pattern is translatable through the token [node:title] in the translation’s language. If the same alias exists in both languages the unique constraint is satisfied, because the uniqueness is per language, but a visitor who changes language without the prefix lands on the other language’s page, so prefix-based negotiation is the safer choice for aliases.

Pathauto stores one pathauto_pattern configuration entity per pattern, edited at Configuration > Search and metadata > URL aliases > Patterns (/admin/config/search/path/patterns, permission administer pathauto). The pattern type is the entity (Content, Taxonomy term, User, and with other modules more), the pattern is a token string, and a pattern can be limited to content types and languages. A blank pattern for one type falls back to the default pattern; if the default is also blank, Pathauto does nothing for that type. Use "Browse available tokens" to find tokens; the usual ones are [node:title], [node:content-type], [node:created:custom:Y], [term:name] and [term:parents:join-path].

Meridian’s scheme is deliberately short and stable. A title-only address is easy to read but collides when two events share a title; adding the year to events solves that without making addresses long.

The exported configuration of the exhibition pattern looks like this (create it in the UI and export it rather than hand-writing the UUIDs).

Source: Pathauto project page

Configuration > Search and metadata > URL aliases > Settings (/admin/config/search/path/settings) holds the module-wide settings stored in pathauto.settings: the separator (a hyphen), the maximum alias length (150 in the shipped default) and component length (100), whether to transliterate to ASCII (on by default, essential for Spanish titles such as "Exposición"), the case rule (lower case), the list of words removed from titles (a, an, the, of and similar), the punctuation handling for each character, and the update action. The update action decides what happens when a title changes: do nothing and keep the old alias, create a new alias and leave the old one working, or overwrite the old alias. The shipped value is the last one, which breaks every inbound link and every search-engine entry to the old address. Whenever aliases are overwritten, install the Redirect module and let it create the redirect from the old address, or switch the site to keep old aliases.

Each content form also has a "Generate automatic URL alias" checkbox, on by default. Unchecking it lets an editor type a custom alias that Pathauto then leaves alone. A checkbox left on by mistake is the source of "my alias keeps changing" tickets.

Aliases are generated when an entity is saved, so content that existed before the module was installed has none. The "Bulk generate" tab (/admin/config/search/path/update_bulk, needing administer pathauto and bulk update aliases) creates aliases for existing entities, and "Delete aliases" (/admin/config/search/path/delete_bulk, bulk delete aliases) removes automatic aliases. In a deployment the same operations are available in Drush.

Source: Pathauto source repository

Bulk regeneration on a site with hundreds of thousands of entities runs through the batch API and can take long; run it from the command line, and do it before a launch, not after, because it changes addresses that search engines already know.

The Redirect module (permission administer redirects, settings need administer redirect settings) stores redirect entities and applies them early in request handling, before a "page not found" would be returned. The list and the add form are at Configuration > Search and metadata > URL redirects (/admin/config/search/redirect); a redirect has a source path (with optional query string), a language, a target (content, path or external URL) and a status code. Settings are at /admin/config/search/redirect/settings, and the shipped defaults, stored in redirect.settings, are these.

Source: Redirect project page

auto_redirect creates a redirect whenever the alias of an entity changes, which closes the gap left by Pathauto’s update action. route_normalizer_enabled redirects non-canonical paths, such as /node/12 for an aliased page and a path without a language prefix, to the canonical one; this is what the older Global Redirect module did, and Global Redirect is therefore no longer needed (older tutorials still recommend it). passthrough_querystring keeps the query string on the redirect target, and access_check makes the redirect depend on access to the target.

Use a permanent status (301) for content that moved for good. Use 302 or 307 only for temporary campaigns; search engines do not transfer ranking through them. The Redirect 404 submodule logs aggregated "not found" requests so an administrator can turn the most frequent into redirects, and can keep them out of the default log.

Meridian renames its "Exhibitions" section to "What’s on". The Pathauto pattern changes and the bulk update rewrites the aliases, but the old address /exhibitions/dinosaur-hall is in guidebooks and search results. With auto_redirect on, each regenerated alias leaves a redirect behind. For addresses that were never aliases (an older site’s /old/dinosaurs.html) a redirect is created by hand, in a migration, or in code.

Source: Redirect project page

A source path is stored without the leading slash; a target is a path or an internal: or entity: URI. For thousands of redirects from a former site, create the entities in a Migrate pipeline (see Migrate API) instead of a loop in a script.

For WordPress and Webflow readers: the equivalent screens are described in Rewrite API and Permalinks and Redirects and Site Migration.

Drupal ships a customised .htaccess file in the project root of the web directory, and this file contains the rewrite. In outline it turns the engine on, optionally forces or removes www. (both commented out), lets you set RewriteBase for a subdirectory install (commented out), and sends everything that is not an existing file or directory, other than the favicon, to the front controller. It also denies access to files that must not be served (.module, .inc, .yml, backups and other sensitive extensions) and to PHP files outside /core except the front controller. The rewrite lines are these.

Source: Drupal core: .htaccess

The virtual host must allow overrides (AllowOverride All) and load mod_rewrite; otherwise the file is ignored, which on a server that ignores .htaccess also removes the protection of private files and the .yml blocks. If the web root is not the project’s web directory, the file is not applied at all. Updating Drupal sometimes changes .htaccess (the 11.4.11 and 10.6.20 releases replaced the assert.active setting with zend.assertions); Composer does not overwrite your customised copy, so compare it with the one in the scaffold after each core update.

Drupal ships no nginx configuration; a request to add an official sample is still open in the core issue queue. The central rule is the equivalent of the Apache lines: try the file, then hand the request to index.php together with the query string. Other rules, for static files and private directories, belong to a complete server block.

Source: Core issue: Provide documentation/default server block for Nginx server

Local DDEV projects generate this configuration for you (see Installation with Composer and DDEV). Hosting requirements, including the end of IIS support in 11.0, are in Requirements and Hosting. Proxies and CDNs in front of the site must also pass the HTMX request headers (HX-Request, HX-Redirect) since 11.3, and must not rewrite the path themselves, or aliases and redirects will not match.