Path mapping for AEM authoring as your content source

When you use AEM authoring as a content source for Edge Delivery Services, path mapping defines how content moves between AEM and your public site. It serves two purposes:

• It maps page paths used on your AEM authoring instance to the public page paths used on your website.
• It controls which content (pages, sheets, assets, etc.) are published to Edge Delivery Services.

It is used by AEM during content publishing and while editing content in the Universal Editor.

For simple setups where AEM paths match the public site paths exactly, path mapping is optional. When mappings are not provided, AEM defaults to publishing all pages under /content/<site>/ at the corresponding public root / (where <site> is the path with the Edge Delivery Services cloud configuration assigned).

Configure a path mapping when you need a different relationship between AEM paths and public URLs — for example:

• DAM assets published under a separate public path (/content/dam/<site>/ → /assets/)
• Localised content branches mapped to shorter URLs

Configuration format

The format of the path mapping configuration contains three sections: mappings, includes, and excludes.

{
  "mappings": [
    "<internal path>:<external path>",
    ...
  ],
  "includes": [
    "<glob pattern>",
    ...
  ],
  "excludes": [
    "<glob pattern>",
    ...
  ]
}

For example, the following configuration sets up a multi-region/multi-language site with a default language at the root, publishes DAM assets under /assets/, exposes a global redirects spreadsheet at /redirects.json, and excludes any drafts subfolder:

{
  "mappings": [
    "/content/site/us/en-us/:/",
    "/content/site/uk/en-gb/:/en-gb/",
    "/content/site/de/de-de/:/de-de/",
    "/content/dam/site/:/assets/",
    "/content/site/redirects:/redirects"
  ],
  "includes": [
    "/content/site/",
    "/content/dam/site/"
  ],
  "excludes": [
    "/content/site/**/drafts/**"
  ]
}

mappings

The mappings configuration holds an array of internal paths (on the AEM authoring instance) and external URL paths (on the public website).

The format is <internal paths>:<external path>.

Mappings use prefix matching against the AEM path; glob patterns (*, **) are not supported in mappings entries.

Spreadsheets are automatically published with a .json extension. The extension is appended by the system, so do not include .json in the external path of a mapping. For example, the mapping /content/site/redirects:/redirects publishes the spreadsheet at /redirects.json.

Examples

• ../path/:/ maps a folder (both ending in /).
• ../path:/anotherpath maps a document to a different path (previously known as a vanity URL).
• ../path/en:/folder/ is a special case and maps the document to /folder/index.

When multiple entries match the same path, the last matching entry wins. Order your mappings from least specific at the top to most specific at the bottom, so that more specific rules override broader catch-all rules.

includes

The includes configuration controls which content paths are actually replicated to Edge Delivery Services. It can hold any array of paths as well and typically contains the site's top-level root page.

includes entries also support glob patterns (* matches a single path segment, ** matches multiple segments). Patterns are matched against the full AEM path only — the filename-only matching available for excludes (e.g. *.xml) does not apply here.

Assets used on Edge Delivery Services pages are typically published alongside the webpage. They will be exported from the AEM authoring instance to Edge Delivery Services automatically.

TIP: If you have a use case where you want assets published directly to Edge Delivery Services (for example you would like images or PDFs to be directly accessible by their URLs outside of a page context), you must add the DAM paths to the includes section of the configuration as well. For example, if an asset root folder such as /content/dam/my-site/documents containing a set of PDF should be publicly accessible via /assets/..., an entry must be added to the includes section of the configuration.

excludes

The excludes configuration controls which content paths are filtered out after the includes have been evaluated. Use it to keep specific paths out of Edge Delivery Services while still publishing them to the AEM author tier — for example, internal pages, draft folders, or sitemap XML files that should remain on the author origin.

A path is published only when it matches an include and does not match any exclude. Includes are evaluated first, then excludes filter the result.

excludes supports glob patterns:

• * matches a single path segment.
• ** matches one or more segments.

Patterns are also evaluated against the filename alone, so file-extension patterns like *.xml work without specifying the full path.

Examples

• /content/site/internal/** — exclude an entire internal subtree.
• /content/site/drafts/** — keep a drafts folder out of the public site.
• *.xml — exclude XML files (e.g. sitemap.xml) from Edge Delivery Services while keeping them on the AEM author tier.

Reserved paths

A small set of public paths is reserved by Edge Delivery Services and is always blocked, regardless of the configuration:

• /config.json — reserved for the Configuration Service. Publishing a spreadsheet that maps to this path is rejected at publish time.
• /.helix/config.json, /.helix/headers.json — legacy file-based configuration paths (no longer supported).

How to configure

Your path mappings can be configured in one of two ways depending on the setup of your project.

1. If the project uses the configuration service for centralized configurations, the paths mapping for each site is configured via this configuration service.
   • Here is an example cURL request to configure path mappings.

curl --request POST \
  --url https://admin.aem.page/config/{org}/sites/{site}/public.json \
  --header 'Content-Type: application/json' \
  --header 'x-auth-token: ......' \
  --data '{
    "paths": {
      "mappings": [
        "/content/site/us/en-us/:/",
        "/content/site/uk/en-gb/:/en-gb/",
        "/content/site/de/de-de/:/de-de/",
        "/content/dam/site/:/assets/",
        "/content/site/redirects:/redirects"
      ],
      "includes": [
        "/content/site/",
        "/content/dam/site/"
      ],
      "excludes": [
        "/content/site/**/drafts/**"
      ]
    }
}'

2. If the project does not use the configuration service, the paths mapping is configured via a paths.json file in your project’s GitHub repository.
   • Here is an example paths.json file.

{
  "mappings": [
    "/content/site/us/en-us/:/",
    "/content/site/uk/en-gb/:/en-gb/",
    "/content/site/de/de-de/:/de-de/",
    "/content/dam/site/:/assets/",
    "/content/site/redirects:/redirects"
  ],
  "includes": [
    "/content/site/",
    "/content/dam/site/"
  ],
  "excludes": [
    "/content/site/**/drafts/**"
  ]
}

In both cases, once you configure your path mappings, you can check the configuration via the publicly-accessible configuration URL https://<branch>--<site>--<org>.aem.page/config.json.