To start, it helps to have a clear understanding of the terminology used:
- A URL is the complete web address for a page: https://www.princeton.edu/academics/library
- A path is just the portion of the URL after the domain name: /academics/library
All content items and taxonomy terms in Princeton Site Builder have a system path. For example, a Page content item may have a system path of "/node/123" and a Page Category taxonomy term may have a system path of "/taxomony/term/3921". These paths are how you access the content directly.
Since these system paths are not very user friendly, a URL alias is automatically created for most content to create a more user-friendly version of the URL. For example, instead if viewing a page via /node/123, an alias allows viewing it via /my-page.
Site admins and content managers can view all of the URL aliases on a site by visiting Configuration » Search and Metadata » URL Aliases.
How Are URL Aliases Generated?
On the form for adding a content item or a taxonomy term, there is a field to specify the URL alias, or to have one generated automatically:
When checking the box to automatically generate one, a pattern is used to assign the alias.
For example, the pattern for "Event" content items generates aliases based on the the title of the event and the year it takes place: /events/2020/my-event-title
The pattern for "Page" content items generates aliases based on the menu link and the menu hierarchy. Note that for the "Page" content type specifically, if you don't create a menu link for it at all, a path will be generated based on the title of the page instead.
Site administrators can view and even customize these patterns by visiting Configuration > Search and Metadata > URL Aliases and clicking the "Patterns" tab. It can be a bit complicated to manage, so we encourage you to engage with WDS support if you have questions.
Of course, if you don't want a URL alias to be automatically generated, just uncheck the box and manually enter one. In this case, follow some best practices:
- Use only lowercase letters
- Don't use spaces or underscores, instead use hyphens
- Exclude commas and apostrophes
- Keep the path concise
Updating URL Aliases on Existing Content
It's common that you need to update the URL alias for content items or taxonomy terms after they have been created.
For content where the "Generate automatic URL alias" checkbox is checked, a URL alias will generate a path based on the pattern as needed.
For example, if you created an event titled "Fall Event" with a start date in October 2020, the URL alias will be "/events/2020/fall-event". Before publishing this event, a colleague indicates that the event has been postponed and will instead take place in the Spring of 2021. When you edit the event to change the title and date, the URL alias will automatically be changed to "/events/2021/spring-event" to reflect the new date. A redirect from the old path to the new one will automatically be created as well, so links to the old path don't break.
If the URL alias was manually entered ("Generate automatic URL alias" is unchecked), simply edit the page and update the path to what you'd like. If you want to remove your manually specified path and have a new path automatically generated, simply clear out the custom path and check the "Generate automatic URL alias" checkbox and save.
Bulk Regenerate URL Aliases
There are a couple of situations where you may need to bulk regenerate URL aliases for a large number of content items that were already created:
- You've changed the pattern used for generating the aliases. For example, changing the pattern for "People" from /people/[node:title] to /about-us/people/[node:title].
- You've changed the menu structure for several pages, and now their aliases need to reflect the new menu hierarchy.
In these cases, URL aliases for content items will not automatically be updated to reflect the new pattern or menu position. Instead, a content manager or site administrator can do one of the following:
- Edit each content item and simply save it again. As long as the "Generate automatic URL alias" checkbox is checked, a new alias will be generated.
- On the main content library page, use the filters and bulk checkboxes to select all items you want to regenerate, and then use the "Regenerate URL Alias" bulk action. This will update the alias for selected pages that already had the "Generate automatic URL alias" checkbox checked. For pages that don't have that feature enabled, they must be edited individually.
For content items that are in the menu, it's important that their URL aliases match the menu structure so that the breadcrumb trail is accurate.