Site Configuration | Yext Hitchhikers Platform

Yext Pages projects include a config.yaml file where settings like build settings, page redirects, and authentication are configured. Each section of the YAML describes a different set of site-wide settings.

Build Configuration

The buildConfiguration section specifies the commands for building the application and installing dependencies, highlighting necessary files like package.json and .npmrc.

Below is how the build settings are configured in the Yext starter repository:

buildConfiguration:
  buildCommand: npm run build
  installDependenciesStep:
    command: npm install
    requiredFiles:
      - package.json
      - package-lock.json
      - .npmrc

• buildCommand: This key specifies the command to be executed for building the application. This script is responsible for compiling the application’s code into a production-ready format.
• installDependenciesStep: This step defines the build process.
  • command: Here, npm install is specified, instructing the system to install the dependencies listed in your package.json file. This is a critical step to ensure that all necessary packages are available for your application.
  • requiredFiles: This is an array of file names that are essential for the dependency installation process. It typically includes:
    • package.json: This file holds various metadata relevant to the project, including the list of dependencies to install.
    • package-lock.json: This file locks the versions of installed packages, ensuring consistency across installations.
    • .npmrc: An optional configuration file for npm (Node Package Manager), which can specify various settings like registry, scopes, and more.

Live Preview Configuration

livePreviewConfiguration contains settings related to the live preview of the application. The starter repository has the following configuration:

livePreviewConfiguration:
  serveCommand: "npm run dev -- --port 8080"
  # setupCommand: ":"

• serveCommand : This command should run a web server on port 8080 which hosts your preview.
• setupCommand (optional): Used to execute any commands that need to be run before the serveCommand step.

Site Stream

The siteStream settings are utilized to create global data that is used site-wide. This includes things like logos and copyright information that you may want to use in every template. The site stream settings must contain an ID for the stream, the Yext Content ID for the entity used in the stream, the fields pulled in from the given entity, and the localization settings:

# The site stream allows for specification of site entity whose data will be injected to all
# generation contexts under the `_site` property.
siteStream:
  id: site-stream
  entityId: site
  fields:
    - name
    - logo
    - c_optionSelectList
  localization:
    locales:
      - en
  transform:
    replaceOptionValuesWithDisplayNames:
      - c_optionSelectList

Check out the Global Data reference doc for more information and a breakdown of the different fields within siteStream.

Static & Dynamic Routes

The staticRoutes and dynamicRoutes sections enables you define rules that specify how incoming requests with certain paths should be handled. “Static” refers to a one-to-one mapping between paths, while “dynamic” means that placeholders and wildcards are used to capture parts of the incoming URL and reinsert them into the destination URL.

# Static routes can establish redirects/rewrites from individual source paths to individual destination paths.
staticRoutes:
  - from: /old-path
    to: /new-path
    status: 301
  # static rewrite
  - from: /user-friendly-url
    to: /internal-content-path/page1.html
    status: 200

# Dynamic routes can establish redirect/rewrite groups based on pattern matching.
dynamicRoutes:
  - from: /articles/*
    to: /blogs/:splat
    status: 302
  # dynamic rewrite
  - from: /help/:articleName
    to: /support/content/:articleName
    status: 200

The URL Routing reference doc provides greater detail on how to utilize these settings.

Sitemaps

The Pages system automatically creates a current sitemap for each deployment, which aids search engines in crawling your site. This reference page from Google explains the relationship between Search engines and sitemaps.

You can edit the sitemap section of the config to add further customization options:

# The sitemap configuration allows for customization or disabling of 
# automated sitemap generation.
sitemap:
  excludeList:
    - exclude1
    - exclude2
#	disableSitemapGeneration: true
#	fileName: custom-name.xml

Check out the Sitemaps reference doc for more information on how the Pages system generates sitemaps and a breakdown of the different fields within sitemap.

Authentication

In the authentication section of the YAML config, you can reference an authentication policy that has been added to the Yext platform in order to protect certain routes:

authentication:
  policyName: auth-policy
  includePaths:
    - /protected-routes/*

Check out the Authentication reference doc to learn more about authentication in Yext Pages.

Response Headers

The responseHeaders section allows you to specify custom response headers for your site. Custom headers facilitate advanced security measures, efficient content delivery, and seamless interaction with reverse proxies and caching layers.

responseHeaders:
  - pathPattern: .*
    headerKey: custom-header
    headerValues:
      - custom-value

You can specify a list of headers in your config.yaml with the following properties:

• pathPattern: This field specifies the URL path pattern that the header settings should apply to. In your example, .* is a regular expression that matches all paths. You can specify different patterns to target specific paths or groups of paths.
• headerKey: This is the name of the HTTP header you want to set or modify.
• headerValues: Here, you define the value(s) for the specified header. These values are what will actually be sent in the HTTP response.

Serving

If you are forwarding requests to your Yext Pages via reverse proxy , you will want to make sure you add your reverseProxyPrefix :

serving:
  reverseProxyPrefix: www.brand.com/subdirectory

Adding this section ensures a few things:

• Your sitemap will be properly generated by properly including the URL prefix in the sitemap paths.
• Assets will be handled properly.
• The authentication callback URL will be properly set relative to the prefix.