Paths and Slugs | Yext Hitchhikers Platform
This article outlines:
- How to define the paths for your pages using the
getPath
function - The
slug
field and how it works - The benefits of using the
slug
field for your paths and best practices - How the
slug
field is required for local development “dynamic mode”
Overview
The slug
field allows a user to define the “path” at which a page of their website is served. For example, if a page is served at www.yext.com/hello/world
, the slug would be hello/world
.
The slug helps to ensure that the paths for your web pages are URL-safe by performing validation and slugification for any inputted strings.
getPath Function
getPath
is a required function in your templates that returns a string. This string defines the path at which the page generated from that template is accessible in production.
Stream Templates
For Stream templates (i.e. pages generated from Streams), we highly recommend returning the slug
field. Refer to the example below:
export const getPath: GetPath<TemplateProps> = ({ document }) => {
return document.slug;
};
Technically, you can return any field (or combination of fields) from your Stream document to getPath
, but you must use the slug
field in order to test your paths during local development.
Static Templates
For static templates (i.e. individual pages that aren’t based on Stream documents), you can simply define your page path by returning a string. Refer to the example below:
export const getPath: GetPath<TemplateProps> = () => {
return `about`;
};
Slugs
Slug
is a field type that ensures your paths are always “URL-safe”. It accomplishes this by doing two things:
Validation: Validates when you attempt to publish a non URL-safe value
For example, here the Content throws an error because the input (“not url safe”) includes spaces.
A legal slug may only contain the following characters:
- Letters (i.e. any character from Unicode categories beginning with “L”)
- Marks (i.e. any character from Unicode categories beginning with “M”)
- Numbers (i.e. any character from Unicode categories beginning with “N”)
- Any of the following characters:
( ) _ ~ : @ ; = / ’ $ * - .
Slugification: Automatically “slugifies” embedded field references
It is extremely useful to include
embedded fields
as part of your slug (refer to the Embedded Fields module to learn more). This allows you to define your page paths based on fields from your entity data. In such scenarios, the slug field automatically converts each embedded reference into a URL-safe string!In the example below, the
slug
is defined as[[address.region]]/[[address.city]]/[[name]]
; assume that the underlying embedded fields evaluate toNY/New York/Turtlehead Tacos
. Theslug
dynamically converts this input tony/new-york/turtlehead-tacos
.Slugification Logic is defined as follows:
- Convert any uppercase letter to lowercase
- Replace any of
- ? & #
with a space - Trim (i.e. remove any leading/trailing whitespace)
- Replace each set of one or more consecutive
whitespace characters
with
-
- Strip any illegal character
Benefits of Slug-Based Paths
It is highly recommended to define the paths for Stream-generated pages based on the slug
field, as opposed to other fields or hardcoded values. This practice offers two major benefits:
By defining paths solely based on the
slug
field, non-developer users have the ability to update production URLs by directly editingslugs
in the Content; no template-level code changes are required!It is required that you return the
slug
in yourgetPath
function to test your production paths during *local development*. The Pages system uses this field specifically to generate page paths during local development. If aslug
value is missing from one of your entities, you will not be able to preview that entity locally using “dynamic mode”.
Disabling Slug-Based” Local Dev URLs
By default, the npm run dev
command will automatically use the slug
field to generate your paths. However, you may have some entities for which the slug field is either not populated or not enabled on the entity type at all; and still want to test use these entities for local development.
If you are using a Yext starter, you can disable this behavior with the following command:
npm run dev -- --no-prod-url
This command will serve your local URLs in the following format, which will only be used locally and will not match what is served in production:
localhost:5173/[template-name]/[entity-id]
Slug Best Practices
To ensure your URLs are always in a clean state, please adhere to the following best practices. Failure to do so may result in page generation failures:
Ensure each entity in your stream has a
slug
value (in other words, ensure your slugs are nevernull
for an entity used to power a page in your site).In case of
null
values in your live production deploy, we recommend you configure a “fallback” path in yourgetPath
function. The starter templates for Pages projects contain sensible defaults like below for location entities.export const getPath: GetPath<TemplateProps> = ({ document }) => { return document.slug ? document.slug : `${document.locale}/${document.address.region}/${document.address.city}/${ document.address.line1 }-${document.id.toString()}`; };
Here we use the location’s
region
,city
, andaddress line 1
to create a unique path.
Ensure that your slugs do not begin with a forward slash (
/
). If your slug begins with a forward slash, this will cause the page to be served at an invalid URL.Ensure each
slug
is unique with respect to other entities used for your site. If any two pages in your site share the same path, both pages will fail to generate.
September ‘23 Release Slug Field Updates
With the September ‘23 monthly release, we have updated certain logic that the slug
field uses. Please refer to the sections below to compare how the slug
field behaved prior to the September ‘23 release vs. after.
Note, if your slugs only contain English non-accented letters, then this update does not affect your account.
Similarly, the slug is used exclusively for websites built on the latest version of Pages, and for customers using the Directory Manager . If your site is on the Classic architecture or Page Builder, these updates most likely do not affect your account.
Please refer to the Types of Pages reference doc to determine if your website is on the latest version of Pages, or reach out to your account team directly.
Next Steps and Action Items
On the day of the September ‘23 monthly release, Yext slugs will abide by the updated logic described below. Yext will automatically trigger a backend bulk-update to ensure that your slugs are re-computed using the new logic. As such, it is possible your slug values will change if there are any updates to your entity profiles.
If any of your slugs are in use for a Pages website, Yext’s redirects system will automatically set up 301 redirects for any slugs that are updated. No action is required in order to benefit from that functionality.
We recommend completing the following action items in order to ensure that your downstream systems are fully up-to-date, however:
Redeploy your Website
- If, for whatever reason, you are seeing “stale” slugs on your website, you can rectify this by re-deploying your site (and subsequently publishing it to production).
- As mentioned earlier, any page paths that update will have 301 redirects set up for the old paths automatically per our automatic redirects system .
- If “stale” slugs remain, you can rectify this by making a trivial update to the
stream object
in your
TemplateConfig
. For example, you can update the name of the$id
. This will guarantee the system requests the most up-to-date data.
- If, for whatever reason, you are seeing “stale” slugs on your website, you can rectify this by re-deploying your site (and subsequently publishing it to production).
Re-run your Directory Manager Instances
- You must re-run the Directory Manager in order to see the updated slugification logic on your entities. Please refer to this unit for instructions on running the DM.
- Note, it is technically possible that slugs for entities generated by the DM may update even without re-running your DM configuration. As mentioned earlier, if this results in updated page paths, 301 redirects will be automatically set up for them via our automatic redirects system .
Prior to the September ‘23 Release
Validation Logic
The slug field validates whether or not an inputted string is legal, and occurs whenever you attempt to save a string to the slug field.
Prior to the September 2023 release, a legal slug could only contain the following characters:
- Lowercase letters
- Numbers (i.e. any character from Unicode categories beginning with “N”)
- Any of the following characters:
( ) _ ~ : @ ; = / $ * - . [ ]
Slugification Logic
The slug field also performs slugification whenever a slug is fetched by downstream systems (e.g. streams and APIs). This entails basic transformations and string replacements.
This is helpful when your slug field is powered by embedded fields , as it protects against illegal characters that the system cannot catch at validation-time.
In this example, the slug is powered by embedded references to the address and entity ID fields. Slugification ensures that if any of those fields have illegal characters in them, they are slugified at request-time.
This logic is defined as follows, and performed in sequential order:
- Convert any uppercase letter to lowercase
- Replace any of
- ? & #
with a space - Trim (i.e. remove any leading/trailing whitespace)
- Replace each set of one or more consecutive
whitespace characters
with
-
- Strip any illegal character
Directory Manager Slugification
The Directory Manager (DM) is a Yext application that creates entities programmatically to power directory-based websites. The Directory Manager can be configured to define slugs for any entities that it creates.
Prior to the September ‘23 monthly release, the Directory Manager outputted slug values via its own slugification rules. Given an incoming string, the DM would slugify any unicode string per the rules defined in this GitHub repo . As such, this converted any international characters into ASCII characters.
September ‘23 Release and Onward
As of the September ‘23 monthly release, Yext has updated the behavior of the slug
field. Please refer to the following sections below:
Validation Logic
Now, a legal slug may contain the following characters:
- Letters (i.e. any character from Unicode categories beginning with “L”)
- Numbers (i.e. any character from Unicode categories beginning with “N”)
- Any of the following characters:
( ) _ ~ : @ ; = / $ * - . [ ]
Slugification Logic
Slugification logic will remain unchanged, with the exception of what “illegal characters” are stripped out. Per the validation logic above, all Unicode letter categories are now permitted, and as such will not be stripped out.
Directory Manager Slugification
Now, the Directory Manager will populate any slug values using the standard slugification logic referenced above.