Directory websites (i.e. directories) are a great way to boost visibility for your brand's locations, products, and services. Directories make it easy for visitors to navigate around and see the full breadth of information your business has to offer.

The example below shows a location-based directory. This page displays the total number of active locations operating in each U.S. state:

From here, a user can drill down into a specific state to narrow their search:

From there, they can drill down further into a city:

The example above showcases a location directory, but directories can be used to organize any type of information in a hierarchy: products, blog posts, services, etc. Directory websites can also be an excellent way to improve your business's SEO.

The Knowledge Graph gives you the freedom to define the custom entity types and fields required for your business's data model. For a U.S. location directory, the underlying Knowledge Graph structure looks something like this:

Creating the initial entities and relationships needed for each page takes significant time — especially if your Knowledge Graph has thousands of entities. Keeping that data up-to-date is even more challenging. This is where the Yext Directory Manager comes in.

The Directory Manager (DM) helps you programmatically construct a directory of entities and relationships in your Knowledge Graph, based on a set of configurable logic. It not only generates the initial entity tree but also actively maintains the logical hierarchy of relationships in response to entity updates. This lets you focus on your core data and Pages development, while Yext takes care of the rest.

At a high level, building a directory involves the following steps:

1. Prepare your Knowledge Graph
2. Configure the Directory Manager
3. Run the Directory Manager
4. Develop your directory site locally
5. Deploy your directory site to the platform

Steps 1–3 can be visualized here:

The conceptual entity hierarchy for a U.S.-based location directory looks like this:

Directory Manager Terminology

Step 1: Prepare Your Knowledge Graph

The first step is to populate your Knowledge Graph with the entity types and custom fields the Directory Manager needs to create your tree.

Note: If you're following the Hitchhikers Pages Track, this module assumes you used the yext pages new command to create a repo with the Locations Starter (basic) template, and that your account is already populated with seed data. If you wish to test the Directory Manager using your own location entities, apply the DM-specific configuration files to your account instead.

In your Yext account, navigate to Admin Console and verify that the following resource files exist:

• km > entity-type
  • root.json
  • state.json
  • city.json

These custom entity types will be used by the Directory Manager. They must exist before the DM can run successfully. If you are using your own account data, create your entity types before referencing them in a DM configuration file.

Step 2: Configure the Directory Manager

1. In Admin Console, click the Add Resource button in the top right.
2. Click Pages > Directory Manager.
3. Name your file us-directory.json.
4. Replace the existing contents with the following JSON, then click Apply and follow the prompts:

{
  "$id": "us-directory",
  "$schema": "https://schema.yext.com/config/pages/directory-manager/v1",
  "name": "US Directory",
  "baseEntities": {
    "entityTypes": ["location"]
  },
  "root": {
    "entityType": "ce_root",
    "slug": "root.html"
  },
  "localization": {
    "locales": ["en"]
  },
  "levels": [
    {
      "entityType": "ce_state",
      "field": "address.region",
      "slug": "{{address.region}}",
      "fieldMappings": {
        "c_addressRegionDisplayName": "{{#regionDisplayName}}"
      }
    },
    {
      "entityType": "ce_city",
      "field": "address.city",
      "slug": "{{address.region}}/{{address.city}}",
      "fieldMappings": {
        "c_addressRegionDisplayName": "{{#regionDisplayName}}"
      }
    }
  ]
}

This JSON object tells the Directory Manager how to construct the tree of entities in the Knowledge Graph. At a high level:

• baseEntities — The set of entities from which the tree will be constructed. Determined by entity types, and optionally saved filters.
• levels — The different levels of the tree. The DM will generate entities based on the field values from the base entities (address.city and address.region) and create relationships between them and all applicable base entities. The slug is powered dynamically by the same values. fieldMappings maps data from the base entities to fields on your tree entities (in this case, converting a state abbreviation like "NY" into a display name like "New York").
• root — Generates a single "root" entity that is the parent of all other nodes in the directory. Typically used to power your index/home page. In this example, the root entity is the direct parent of all state entities.
• localization — The set of language locales to construct for your directory entities. See the Multi-Language Directories section for more information.

Step 3: Run the Directory Manager

In your Yext account, navigate to Pages > Directory Manager. You will see the configuration file you created. Click the dropdown and select Run.

Shortly after, you will see two updates:

1. Status — Indicates the DM is actively maintaining a tree of entities in your account.
2. Live Entities — The count of entities generated by the DM.

Explore the Generated Data

Entities: Navigate to Knowledge Graph > Entities. You will notice new entities: a Root entity, State entities, and City entities — all generated based on the address fields from your location entities.

Saved Filters: Click the Saved Filter icon in the top right. The Directory Manager created three saved filters — one per level of the tree (root, state, and city). Click "us directory - address.city" to examine the criteria. It filters for any entities where:

• Entity Type = "City"
• Fields with Data = "Directory Children" (only entities related to at least one child entity)
• Directory Manager ID = "us-directory" (scopes the filter to your specific tree, in case you have multiple)

Relationships: Click on the New York (city) entity. The Directory Manager populated the following fields:

• Directory Parents — The full ancestry above this entity. For New York City, this would be New York (state) and the root entity.
• Directory Children — All location entities that have an address in New York City.
• Directory Children Count — The total count of those children.

Click on one of the location entities and look for the Directory Parents field — it will list "Root", "New York (state)", and "New York (city)". The DM creates all necessary relationships automatically, enabling easy traversal of the entire tree from your frontend code.

Directory Manager Details Page

Navigate back to Pages > Directory Manager and click View on your US Directory. This takes you to the Directory Details page, which displays:

1. Directory Summary — A summary of your configuration file.
2. Document Logs — A table of Knowledge Graph updates the DM made in response to each base entity. Click into each log to inspect the set of actions. If your entity tree is ever in an unexpected state, use this UI to determine what went wrong.

Step 4: Build Your Directory Frontend

Now that the Directory Manager has created your entity tree, update your Pages templates to incorporate that data.

Update TemplateConfig and transformProps

Your root.tsx, state.tsx, city.tsx, and location.tsx templates have commented-out code for the directory-specific fields. Uncomment the code in the TemplateConfig and transformProps for each template.

Here is the final state of city.tsx after uncommenting:

export const config: TemplateConfig = {
  stream: {
    $id: "city-stream",
    filter: {
      entityTypes: ["ce_city"],
    },
    fields: [
      "id",
      "uid",
      "meta",
      "name",
      "description",
      "slug",
      "c_addressRegionDisplayName",
      "dm_directoryParents_us_directory.name",
      "dm_directoryParents_us_directory.slug",
      "dm_directoryParents_us_directory.meta",
      "dm_directoryParents_us_directory.c_addressRegionDisplayName",
      "dm_directoryChildren.name",
      "dm_directoryChildren.address",
      "dm_directoryChildren.mainPhone",
      "dm_directoryChildren.slug",
    ],
    localization: {
      locales: ["en"],
    },
  },
};

export const transformProps: TransformProps<any> = async (data) => {
  const { dm_directoryParents_us_directory, name } = data.document;

  (dm_directoryParents_us_directory || []).push({ name: name, slug: "" });

  return {
    ...data,
    document: {
      ...data.document,
      dm_directoryParents: dm_directoryParents_us_directory,
    },
  };
};

Note: This code assumes your Directory Manager configuration ID is us-directory. If your DM ID differs, update dm_directoryParents_[dm_ID] accordingly.

Repeat this process for state.tsx, location.tsx, and root.tsx. Note that root.tsx does not have a transformProps function.

Preview Your Site Locally

Start your local dev server:

npm run dev

The Yext Pages Development page will open in your browser. You will notice several new types of entity pages generated for the root, state, and city entities.

Navigating through the site:

1. Root page (http://localhost:5173/root.html) — Powered by DirectoryRootGrid.tsx. Displays a full list of states with active locations. Data comes from dm_directoryChildren.name, .slug, .c_addressRegionDisplayName, and .dm_childEntityIds.
2. State page (click New York) — Powered by DirectoryStateGrid.tsx. Displays all cities in that state. Includes breadcrumbs for navigation back to the root page (powered by Breadcrumbs.tsx). Data comes from dm_directoryParents_us_directory.*, dm_directoryChildren.*, and dm_childEntityIds.
3. City page (click New York (city)) — Powered by DirectoryCityGrid.tsx. Displays all location entities based in that city. Data comes from dm_directoryParents_us_directory.* and dm_directoryChildren.* (name, address, mainPhone, slug).

Update Your Home Page

The default home page is powered by static.tsx. To replace it with your root directory page:

1. Delete static.tsx from your src/templates folder. Your index page will 404 temporarily.
2. In Knowledge Graph > Entities, locate your Root entity. Update the slug field from root.html to index.html.
3. Reload http://localhost:5173/index.html. Your index page is now powered by your root entity, and users can navigate your full directory from the home page.

Update Your Saved Filters

As a best practice, use the saved filters created by the DM (rather than entity types) in your Stream template filter configs. This ensures your frontend only generates pages for entities in your specific US Directory tree — important if your account ever has multiple entity trees with overlapping entity types.

First, navigate to Knowledge Graph > Configuration > Saved Filters to find the three saved filters the DM generated:

Then update the filter object in each template:

root.tsx:

export const config: TemplateConfig = {
  stream: {
    $id: "root-stream",
    filter: {
      savedFilterIds: ["dm_us-directory"],
    },
    // ...
  },
};

state.tsx:

export const config: TemplateConfig = {
  stream: {
    $id: "state-stream",
    filter: {
      savedFilterIds: ["dm_us-directory_address_region"],
    },
    // ...
  },
};

city.tsx:

export const config: TemplateConfig = {
  stream: {
    $id: "city-stream",
    filter: {
      savedFilterIds: ["dm_us-directory_address_city"],
    },
    // ...
  },
};

You won't notice any visual differences after these changes, but this is a best practice to keep your entity tree and Pages frontend in lockstep.

Step 5: Deploy

Commit your changes to GitHub and publish to your production site. If you need a refresher, refer to the deployment module.

Note: Check for errors in the deployment screen. If you encounter any URL collision errors, ensure that your directory templates are not generating any of the same URLs.

Directory Manager Schema Reference

The Directory Manager is powered by a JSON configuration file. Here is the full list of available properties:

Updating a Directory Manager Configuration

To update an existing DM configuration:

1. Go to your Yext account and open Admin Console (found in the Developer section of the left nav, or via Quick Find).
2. Open pages > directory-manager, and click on your desired DM configuration file.
3. Update the file with the desired changes.
4. Click Apply in the top right and follow the prompts.
5. Navigate to Pages > Directory Manager, click the dropdown next to your DM, and select Run to recreate your tree using the updated configuration.
   • Alternatively, re-run via the CLI:
     1. yext init
     2. yext dm run --cacId="[REPLACE_ME]"
6. Navigate back to the Knowledge Graph. You should see the updated changes reflected in your data.

Directory Manager Execution Process

Once the Directory Manager runs, it:

1. Adds the following custom fields to the entity types in your account:
   • Directory Parents (dm_directoryParents_[dm_directoryManagerId]) — The dm_directoryManagerId is appended to disambiguate, in case you have multiple active directories.
   • Directory Children (dm_directoryChildren)
   • Directory Children Count (dm_directoryChildrenCount)
   • Directory Manager ID (dm_directoryManagerId)
   • Child Entity IDs (dm_childEntityIds)
2. Generates your directory entities.
3. Creates a saved filter for each level of your directory.

The DM creates a saved filter for each level of your tree, including all entities created at that level. Importantly, these filters only include entities that have directory children. If a Directory Entity no longer has any child entities, it will no longer meet the criteria for your saved filters.

Ongoing Directory Maintenance

The DM remains active in your account after initialization and listens for ongoing CRUD operations involving the set of base entities.

Entity Creation

When you add a new location entity, the DM updates the directory automatically — no need to re-run it.

In the example below, the user adds location 5 based in Chicago, IL — a city and state not yet in the directory. The DM creates the Chicago city entity, the Illinois state entity, and all relationships between them. The directory children count for the root entity changes from four to five.

Entity Updates

The same is true for updates to existing entities.

In the example below, the user moves location 2 from New York, NY to Brooklyn, NY. The DM creates a new Brooklyn city entity, relates it to the NY state entity, and updates location 2's related city. The directory children count for New York (city) changes from two to one, and Brooklyn is set to one.

Entity Deletions

If you delete a location, the DM ensures any relevant directory entities are no longer related to it and removes them from the directory entirely if they have no remaining children.

In the example below, the user deletes location 1 in Brooklyn, NY. Brooklyn now has no related children entities, so the DM removes it from the directory. The directory children count for NY state and the root entity are updated accordingly.

Advanced Configuration Use Cases

Multi-Level Directories (aka "Skip" Level Directory)

The Directory Manager supports configurations where base entities may have differing lengths of parent ancestry. For example, in the U.K., address.region is often not populated.

For a given base entity, the DM attempts to create directory entities starting at the deepest level and working up to root (address.city → address.region → address.country). When it cannot find a value for a level, it automatically skips that level and proceeds to the next. You can configure all expected levels in your config — if a value isn't found for a particular base entity, the DM simply skips it.

{
  "$id": "multi-level-directory",
  "$schema": "https://schema.yext.com/config/pages/directory-manager/v1",
  "name": "Multi-Level directory",
  "baseEntities": {
    "entityTypes": ["location"],
    "savedFilterIds": ["[savedFilterId]"]
  },
  "localization": {
    "locales": ["en"]
  },
  "root": {
    "entityType": "ce_root",
    "slug": "index.html"
  },
  "levels": [
    {
      "entityType": "ce_country",
      "field": "address.countryCode",
      "slug": "{{address.countryCode}}",
      "fieldMappings": {
        "c_addressCountryDisplayName": "{{#countryDisplayName}}"
      }
    },
    {
      "entityType": "ce_region",
      "field": "address.region",
      "slug": "{{address.countryCode}}/{{address.region}}",
      "fieldMappings": {
        "c_addressCountryDisplayName": "{{#countryDisplayName}}"
      }
    },
    {
      "entityType": "ce_city",
      "field": "address.city",
      "slug": "{{address.countryCode}}/{{address.region}}/{{address.city}}",
      "fieldMappings": {
        "c_addressRegionDisplayName": "{{#regionDisplayName}}"
      }
    }
  ]
}

If you encounter slug collisions between levels that share the same name (e.g., Barcelona city within Barcelona region), set collapseSlugs to false. This causes the DM to place a hyphen in the slug to denote when a level was skipped, ensuring unique paths.

Entity Templates

An entity template is a Knowledge Graph tool that allows you to define a "template" of field values and apply it to a set of entities at scale. The Directory Manager extends this by allowing you to apply specific templates any time a directory entity is generated, using the entityTemplateId property.

In the example below, two entity templates are used:

1. stateTemplate — Sets the description field to "Welcome to [[name]], located in the great nation of [[c_addressCountryDisplayName]]!"

   

2. cityTemplate — Sets the description field to "Welcome to [[name]], located in the great state of [[c_addressRegionDisplayName]]!"

   

Note: These examples use embedded fields to make descriptions dynamic per entity.

{
  "$id": "us-directory",
  "$schema": "https://schema.yext.com/config/pages/directory-manager/v1",
  "name": "US Directory",
  "baseEntities": {
    "entityTypes": ["location"],
    "savedFilterIds": ["685381454"]
  },
  "root": {
    "entityType": "ce_root",
    "slug": "index.html"
  },
  "localization": {
    "locales": ["en"]
  },
  "levels": [
    {
      "entityType": "ce_state",
      "field": "address.region",
      "slug": "{{address.region}}",
      "entityTemplateId": "stateTemplate",
      "fieldMappings": {
        "c_addressRegionDisplayName": "{{#regionDisplayName}}",
        "c_addressCountryDisplayName": "{{#countryDisplayName}}"
      }
    },
    {
      "entityType": "ce_city",
      "field": "address.city",
      "slug": "{{address.region}}/{{address.city}}",
      "entityTemplateId": "cityTemplate",
      "fieldMappings": {
        "c_addressRegionDisplayName": "{{#regionDisplayName}}"
      }
    }
  ]
}

Once the DM runs, the relevant template is applied to each generated entity. The description field is automatically populated for both New York (state) and New York (city):

These dynamic fields then power your Pages frontend:

Multi-Language Directories

For each base entity, the DM generates equivalent language profiles for each entity in its parent ancestry.

Location 1 (based in New York, NY) has language profiles for ["en", "es"]. This cardinality is respected across its parent ancestry — the DM creates both "en" and "es" profiles for the New York city, New York state, and root entities.

By contrast, Location 3 does not have an "es" profile, so its ancestry only has "en" profiles. Streams respects language profile cardinality — the "es" profile for the root entity will not have "California" as a child entity because it does not exist.

The example configuration below creates a multi-language directory with per-locale entityTemplate overrides:

{
  "$id": "us-directory",
  "$schema": "https://schema.yext.com/config/pages/directory-manager/v1",
  "name": "US Directory",
  "baseEntities": {
    "entityTypes": ["location"]
  },
  "localization": {
    "locales": ["en", "es", "fr"]
  },
  "root": {
    "entityType": "ce_root",
    "slug": "index.html",
    "entityTemplateId": "rootTemplate",
    "localeOverrides": {
      "es": {
        "entityTemplateId": "rootTemplate-spanish",
        "slug": "index/{{localeCode}}"
      },
      "fr": {
        "entityTemplateId": "rootTemplate-french",
        "slug": "index/{{localeCode}}"
      }
    }
  },
  "levels": [
    {
      "entityType": "ce_state",
      "field": "address.region",
      "slug": "{{address.region}}",
      "entityTemplateId": "stateTemplate",
      "fieldMappings": {
        "c_addressRegionName": "{{#regionDisplayName}}",
        "c_addressCountryDisplayName": "{{#countryDisplayName}}"
      },
      "localeOverrides": {
        "es": {
          "entityTemplateId": "stateTemplate-spanish",
          "slug": "{{localeCode}}/{{address.region}}"
        },
        "fr": {
          "entityTemplateId": "stateTemplate-french",
          "slug": "{{localeCode}}/{{address.region}}"
        }
      }
    },
    {
      "entityType": "ce_city",
      "field": "address.city",
      "slug": "{{address.region}}/{{address.city}}",
      "entityTemplateId": "cityTemplate",
      "fieldMappings": {
        "c_addressRegionName": "{{#regionDisplayName}}"
      },
      "localeOverrides": {
        "es": {
          "entityTemplateId": "cityTemplate-spanish",
          "slug": "{{localeCode}}/{{address.region}}/{{address.city}}",
          "fieldMappings": {
            "c_addressRegionName": "{{#regionDisplayName}}"
          }
        },
        "fr": {
          "entityTemplateId": "cityTemplate-french",
          "slug": "{{localeCode}}/{{address.region}}/{{address.city}}",
          "fieldMappings": {
            "c_addressRegionName": "{{#regionDisplayName}}"
          }
        }
      }
    }
  ]
}

"Overlapping" Directories

In some scenarios, you may want to create multiple directories that share the same set of base entities — for example, one directory for banks with ATMs and a separate directory for ATMs only.

To accomplish this:

1. Create two saved filters — one for "banks", one for "ATMs" — with entities that may overlap.
2. Create two Directory Manager configurations: banks-directory and atms-directory.
3. Run the Directory Manager.

As a result, the DM creates both directories. Base entities will have two parent fields: dm_directoryParents_banks-directory and dm_directoryParents_atms-directory. Any overlapping base entity is incorporated into each relevant directory; the parents field includes the Directory Manager ID to disambiguate which directory a given entity belongs to.

Flat Directory

A flat directory has no levels — it simply relates a set of base entities directly to a singular root entity. This is useful when you want to keep a full set of data actively related to one entity, most likely for entity relationships.

To create a flat directory, omit the levels array:

{
  "$id": "flat-directory",
  "$schema": "https://schema.yext.com/config/pages/directory-manager/v1",
  "name": "Flat directory",
  "baseEntities": {
    "entityTypes": ["location"],
    "savedFilterIds": ["[savedFilterId]"]
  },
  "localization": {
    "locales": ["en"]
  },
  "root": {
    "entityType": "ce_root",
    "slug": "index.html"
  }
}

"Primary-Only" Language Directories

For highly complex multi-language implementations, you can configure the DM to populate the slug field for directory entities using data exclusively from your primary language profiles. Set usePrimaryLocaleOnlyForSlug to true.

Assuming English is primary, the values for {{address.region}} and {{address.city}} in any slug will be populated based on English base entity language profiles only.

{
  "$id": "us-directory-primary-only",
  "$schema": "https://schema.yext.com/config/pages/directory-manager/v1",
  "name": "US Directory (Primary Only)",
  "usePrimaryLocaleOnlyForSlug": true,
  "baseEntities": {
    "entityTypes": ["location"]
  },
  "localization": {
    "locales": ["en", "es"]
  },
  "root": {
    "entityType": "ce_root",
    "slug": "index.html",
    "localeOverrides": {
      "es": {
        "slug": "index/{{localeCode}}"
      }
    }
  },
  "levels": [
    {
      "entityType": "ce_state",
      "field": "address.region",
      "slug": "{{address.region}}",
      "fieldMappings": {
        "c_addressRegionName": "{{#regionDisplayName}}",
        "c_addressCountryDisplayName": "{{#countryDisplayName}}"
      },
      "localeOverrides": {
        "es": {
          "slug": "{{localeCode}}/{{address.region}}"
        }
      }
    },
    {
      "entityType": "ce_city",
      "field": "address.city",
      "slug": "{{address.region}}/{{address.city}}",
      "fieldMappings": {
        "c_addressRegionName": "{{#regionDisplayName}}"
      },
      "localeOverrides": {
        "es": {
          "slug": "{{localeCode}}/{{address.region}}/{{address.city}}",
          "fieldMappings": {
            "c_addressRegionName": "{{#regionDisplayName}}"
          }
        }
      }
    }
  ]
}