The slug field allows a user to define the "path" at which a page is served. For example, if a page is served at www.yext.com/hello/world, the slug would be hello/world.

The slug ensures that page paths are URL-safe by performing validation and slugification on any inputted strings.

getPath Function

getPath is a required function in your templates that returns a string defining the path at which the page generated from that template is accessible in production.

Stream Templates

For stream templates (pages generated from Streams), it is highly recommended to return the slug field:

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 to test your paths during local development.

Static Templates

For static templates (individual pages not based on stream documents), define the path by returning a string:

export const getPath: GetPath<TemplateProps> = () => {
  return `about`;
};

Slugs

The slug field type ensures your paths are always URL-safe by doing two things:

1. Validation

Validates when you attempt to publish a non URL-safe value. For example, the Knowledge Graph throws an error if the input includes spaces.

A legal slug may only contain the following characters:

• Letters (any character from Unicode categories beginning with "L")
• Numbers (any character from Unicode categories beginning with "N")
• Any of the following: ( ) _ ~ : @ ; = / ' $ * - . &

2. Slugification

Automatically "slugifies" embedded field references.

Including embedded fields as part of your slug lets you define page paths based on entity data. The slug field automatically converts each embedded reference into a URL-safe string.

For example, if slug is defined as [[address.region]]/[[address.city]]/[[name]] and the embedded fields evaluate to NY/New York/Turtlehead Tacos, the slug dynamically converts this to ny/new-york/turtlehead-tacos.

Slugification logic:

1. Convert any uppercase letter to lowercase
2. Replace any of - ? # with a space
3. Trim 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 paths for stream-generated pages using the slug field rather than other fields or hardcoded values, for two key reasons:

1. Non-developer users can update production URLs by directly editing slugs in the Knowledge Graph — no template-level code changes required.
2. The slug field is required to test production paths during local development. The Pages system uses this field specifically to generate page paths locally. If a slug value is missing from an entity, you will not be able to preview that entity locally using dynamic mode.

Using an Alternate Slug Field in Local Development

Note: You must be using at least PagesJS v1.0.0-rc.9 to use this feature.

If you want to override the default slug field used for local development, add a slugField to your TemplateConfig to reference an alternate slug field:

export const config: TemplateConfig = {
  stream: {
    $id: "locations",
    fields: ["id", "name", "address", "c_alternateSlug"],
    filter: {
      entityTypes: ["location"],
    },
    localization: {
      locales: ["en"],
    },
  },
  slugField: "c_alternateSlug",
};

Disabling Slug-Based Local Dev URLs

By default, npm run dev automatically uses the slug field to generate paths. If you have entities where the slug field is not populated or not enabled on the entity type, you can disable this behavior:

npm run dev -- --no-prod-url

This serves local URLs in the following format (used only locally, not matching production):

localhost:5173/[template-name]/[entity-id]

Slug Best Practices

To ensure URLs are always in a clean state and avoid page generation failures:

1. Ensure each entity in your stream has a slug value — slugs should never be null for an entity used to power a page. For null value fallbacks, configure a fallback path in your getPath function. The starter templates include sensible defaults like:

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()}`;
};

2. Ensure slugs do not begin with a forward slash (/). A leading slash will cause the page to be served at an invalid URL.
3. Ensure each slug is unique across all entities used for your site. If two pages share the same path, both will fail to generate.