URL Routing | Yext Hitchhikers Platform

Overview

URL routing, encompassing URL redirection and URL rewriting, is a powerful technique used to manage how URLs are handled and accessed within your site. It allows a single page or resource to be accessible through multiple URLs or paths, and also enables the dynamic modification of URLs based on predefined patterns. URL routing is essential for creating an efficient, user-friendly, and SEO-optimized website experience.

Common use cases for URL routing include:

Redirection: Redirecting users to a different page during site maintenance or downtime, or when navigating from outdated URLs to updated ones (e.g., redirecting from an old bookmarked link to the current page).
URL Shortening and Aliasing: Creating shorter, more memorable URLs (e.g., redirecting from /bob.html to /agents/US/NY/manhattan/bob.html) or aliasing URLs (like how maps.google.com redirects to google.com/maps ).
Rewriting: Internally mapping a URL to a different endpoint without changing the URL in the browser, which is useful for creating cleaner URLs or consolidating multiple pages under a single path.
Dynamic Routing: Utilizing placeholder and wildcard patterns to dynamically redirect or rewrite URLs based on matching rules, which is particularly powerful for large sites with numerous pages that follow similar URL structures.

With these capabilities, URL routing not only improves site navigation and user experience but also assists in maintaining the site’s structural integrity and relevance in search engine results.

Automatic Routing

The Yext Pages system also provides automatic rerouting when the slug field changes on an entity in the Yext platform (see the System-Generated Redirects ).

Route Configuration

Routing can be configured by developers in three different ways:

File-based configuration: define staticRoutes and/or dynamicRoutes settings in config.yaml
CSV: add a redirects.csv file to the root of the Pages repo
Template-level redirects: define a getRedirects function in a template

File-Based Configuration in config.yaml

staticRoutes and dynamicRoutes provide configurations for URL redirects, supporting both individual path redirects and pattern-matching group redirects, with specified HTTP status codes indicating the nature of each reroute (redirect or rewrite).

Status Codes

The following status codes can be used when specifying redirects:

301 (Moved Permanently)
302 (Found)
303 (See Other)
307 (Temporary Redirect)
308 (Permanent Redirect)

When creating a rewrite, you will specify status: 200. This indicates to the Pages serving system to serve the contents of the to path at the from path.

You can read more about HTTP status codes in this MDN reference doc .

Static Redirects

Static redirects and rewrites are used to forward or translate individual URL paths to individual destinations. This can be essential for a number of reasons such as creating redirects as part of a vendor migration where the URL structure changed requiring traffic to be redirected from old to new content, or creating friendly URLs for marketing purposes.

# Static redirects can establish redirects from individual source paths to
# individual destination paths.
staticRoutes:
  - from: /old-path
    to: https://www.yoursite.com/new-path
    status: 301 # 301 is the status code for a permanent redirect.

In this example, anyone visiting www.yoursite.com/old-path would be permanently redirected to https://www.example.com/new-path. The 301 status code tells the browser (and search engines) that the page has moved permanently, which is also beneficial for SEO as it passes the link equity to the new URL.

Static Rewrite

A static rewrite is used to internally map one URL to another without the URL changing in the browser’s address bar. This means the user sees the original URL they typed in, but the server serves the content from the rewritten path.

staticRoutes:
  - from: /user-friendly-url
    to: /internal-content-path/page1.html
    status: 200 # 200 status code means the content is served directly.

In the above static rewrite example, when a visitor goes to www.yoursite.com/user-friendly-url, the server serves the content from https://www.yoursite.com/internal-content-path/page1.html, but the URL remains www.yoursite.com/user-friendly-url in the visitor’s browser.

Dynamic Redirects & Rewrites

Dynamic routes are redirects and rewrites with placeholders and wildcards allowed in the source and destination URLs.

Placeholder Values

Placeholder values are used to create dynamic routes that capture parts of the incoming URL and reinsert them into the destination URL in a specified order. This allows for the creation of more adaptable and scalable routing logic.

dynamicRoutes:
  - from: /shop/:category/:productID
    to: /product/:productID/category/:category
    status: 302 # A temporary redirect status code

In this configuration, :category and :productID are placeholders for dynamic parts of the URL. The placeholders capture the relevant segments from the original URL and insert them into the new path.

For example, if someone accesses /shop/books/12345, the dynamic redirect would send them to /product/12345/category/books.

Wildcard Values

Wildcard values are indicated by an asterisk (*) and are useful for matching a sequence of path segments in the URL. They are particularly helpful when the exact path is not known in advance or when it is necessary to match a large number of URL patterns.

dynamicRoutes:
  - from: /articles/*
    to: /blog/:splat
    status: 302 # A temporary redirect status code

In the example provided, the wildcard * matches any sequence after /articles/. The :splat placeholder represents the sequence matched by the wildcard. For instance, a request to /articles/2023/march/spring-gardening-tips would dynamically redirect to /blog/2023/march/spring-gardening-tips.

You could also omit the :splat placeholder to route any URL that matches the sequence to an individual destination URL.

Dynamic Rewrites

A dynamic rewrite is like a dynamic redirect but without the URL change in the client’s address bar, creating clean and user-friendly URLs while serving the desired content.

dynamicRoutes:
  - from: /help/:articleName
    to: /support/content/:articleName
    status: 200 # The content is served without changing the URL.

With the above rewrite rule, when a user visits /help/installation-guide, the content from /support/content/installation-guide is served, but the URL stays as /help/installation-guide in the browser.

Add CSV File to Repo

You can add a redirects.csv file to the root of your repository to upload redirects in bulk. Your file should contain two columns:

Original URL (previous path)
Destination URL (new path)

Note that you should not add any column headers. Here is an example file:

/old-path,/new-path
/about.html,/about-v2.html

To host these redirects, deploy your site with this CSV file.

Note: if any collisions are detected on deploy (e.g., one source path redirects to two different destinations), the deploy will fail, and you will be notified to fix your file.

Template-Level Redirects

Template-level redirects allow you to specify redirects directly within your template files. This method is particularly useful for dynamically creating redirects based on the content or properties of individual pages. The function returns an array of paths that are mapped to the path specified in getPath.

/**
 * Defines a list of paths which will redirect to the path created by getPath.
 *
 * NOTE: This currently has no impact on the local dev path. Redirects will be set up on
 * a new deploy.
 */
export const getRedirects: GetRedirects<TemplateProps> = ({ document }) => {
  return [`index-old/${document.locale}/${document.id.toString()}`];
};

Route Ordering

Routes are applied in the following priority order:

Content & Serverless Functions
Static Routes
Dynamic Routes

This is best understood with a few examples.

Example 1

Let’s say you have a page served at locations/old-store-page and the following configuration:

staticRoutes:
  - from: /locations/old-store-page
    to: /locations/new-store-page
    status: 301

If a user navigates to your-brand.com/locations/old-store-page, the redirect WILL NOT occur because content is being served at your-brand.com/locations/old-store-page. Once you take down the old store page, the user will be redirected to the new store page.

Example 2

Take a look at the following configuration:

staticRoutes:
  - from: /locations/big-awesome-store
    to: /locations/flagship-store
    status: 301
dynamicRoutes:
  - from: /locations/*
    to: /stores/:splat
    status: 301

Since static routes take precedence over dynamic routes, a user visiting your-brand.com/locations/big-awesome-store will be redirected to your-brand.com/locations/flagship-store AND NOT your-brand.com/stores/big-awesome-store.

Back

< Robots.txt

System-Generated Redirects >

Feedback

<% elem.innerText %>