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:
  1. Letters (i.e. any character from Unicode categories beginning with “L”)
  2. Marks (i.e. any character from Unicode categories beginning with “M”)
  3. Numbers (i.e. any character from Unicode categories beginning with “N”)
  4. 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 to NY/New York/Turtlehead Tacos. The slug dynamically converts this input to ny/new-york/turtlehead-tacos.
- Slugification Logic is defined as follows:
  1. Convert any uppercase letter to lowercase
  2. Replace any of - ? & # with a space
  3. Trim (i.e. remove any leading/trailing whitespace)
  4. Replace each set of one or more consecutive whitespace characters with -
  5. 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 editing slugs in the Content; no template-level code changes are required!
It is required that you return the slug in your getPath function to test your production paths during *local development*. The Pages system uses this field specifically to generate page paths during local development. If a slug 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 never null 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 your getPath 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, and address 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

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
1. 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).
  1. As mentioned earlier, any page paths that update will have 301 redirects set up for the old paths automatically per our automatic redirects system .
2. 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.
Re-run your Directory Manager Instances
1. 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.
2. 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.

Back

< Global Data (< PagesJS 1.0.0)

Environment Variables >

Feedback

<% elem.innerText %>