DocumentationAEM GuidesAEM Guides Documentation

Additional features in the Map Editor id1942D0T0HUI

Last update: July 28, 2026

CREATED FOR:

  • User

Some common features in the Map Editor are:

Resolve key references id176GD01H05Z

A DITA content key reference, or conkeyref is a mechanism for inserting a part of content from one topic into another. This mechanism uses key to locate the content to reuse rather than the direct content referencing mechanism. For more information about direct and indirect referencing in DITA, view DITA addressing in OASIS DITA Language Specification.

If the DITA topic has associated key references, then they need to be resolved before previewing, editing or reviewing a topic.

The key references are resolved on the basis of the root map set in the following order of priority:

  1. User Preferences
  2. Map View panel
  3. Folder Profile

The root map selected in the User Preferences takes the highest precedence to resolve key references followed by Map View panel and the Folder Profile root map. So, if no map is set in the User Preferences, then the map opened in the Map View panel is used. If no map is opened in the Map View panel then the map set in the Folder Profiles is used to resolve the key references.

The key references can be stored within a DITA map file or a separate DITA file. In Experience Manager Guides, you can specify key references either at the project level or a session level. If a root map is already defined for the user session, then it is used for resolving the keys. Else, the default root map for that folder is used. In case a default root map is not configured, then the missing key references are highlighted to the user.

There are several ways to resolve key references in a DITA topic by defining the DITA map to be used at the following locations:

Project properties - You can define a root map for resolving key references while creating a Project in the Project Properties section.

This root map will be applicable for all assets (folders and sub-folders) associated with that project. For content that is referenced in multiple projects, an alphabetical list of projects is maintained and the default root map associated with the first project is used. You can also choose the DITA map to be used from the list for resolving key references.

Topic preview - In the topic preview mode, select the Key Resolution icon in the toolbar and select the DITA file to be used for key references.

Topic edit view - Select the Key Resolution icon while editing a DITA topic and select the DITA file to use for resolving the key references.

Add navigation references

The navref element is used inside a DITA map to include navigation references from another DITA map. This allows authors to reuse navigation structure, such as shared menus or links, without merging the actual content of the referenced map into the output.

NOTE
The navref element is intended solely for navigation purposes within the map structure. It does not contribute to the generated DITA map output and is excluded from processing and display in the Map view, Reports, Baseline, Translation, and Preview.

To add navigation references to a map, perform the followin steps:

  1. Open the DITA map file where you want to add a navigation reference.

    The map file opens in the Map Editor.

  2. Switch to the Author view and place the cursor at a valid location for a navigation reference.

  3. Select the Element option from the toolbar.

  4. In the Insert element dialog, select navref.

  5. The Select path dialog is displyed. Select a map file you want to include as navigation reference in your map, and choose Select.

A navigation reference of the selected map file is added at the specified location. Also, the title of referenced map is displayed in both Author view and Layout view.

Author view

Layout view

Run health check on a map

The Run health check option in the context menu allows you to run a health check on the selected map to catch issues such as broken links, duplicate IDs, and Schematron validation failures before publishing.

NOTE
This feature is enabled by default. If you prefer not to use this feature in your environment, contact your Customer Success team.

Which checks are available to run is defined by a health check preset, created and managed by an Administrator at the folder-profile level. For more details, view Create and manage health check presets.

Perform the following steps to run a health check on a map:

  1. Open a map in the Editor.

  2. In the Options menu, select Run health check option.

  3. The Run health check dialog is displayed. Select a health check preset you want to run. Only the presets configured for your folder profile are available for selection.

    Selecting a preset, loads the defined checks in the dialog.

  4. Optional Select a Baseline. If you don’t want to use a baseline, select None.

  5. Select Run.

You can also run a health check on a map from the Health check report panel. For this, open a map in Map view, and select the Health check report icon.

NOTE
This option is displayed only for a map on which no health check has been run yet. If a health check has already been run on the map, selecting the Health check report icon opens the existing report instead.

In the panel, select Run health check.

This opens the same Run health check dialog where you can select a health check preset and a baseline to run a health check on the map, as described in the above steps.

Using the health check report in the Editor

When you run a health check for a map, the report opens in the Health check report panel as shown below:

Health check report panel options

The following options are available in the Health check report panel:

  • Map name: The name of the map the report was generated for.
  • Info icon: Select to view the preset name, map version, and baseline (if any) used to generate the report.
  • Filter: Narrows the report to a specific rule, for example to view only the Broken links results. The filter only lists the rule types that produced results in the current report.
  • Download report: Downloads the report.
  • Regenerate: Runs the health check again.

Health check results

Each result produced by the selected checks is listed with the following details:

  • Severity: The severity level of the result, for example Error, Warning, Info, or Fatal.
  • Health check preset name: Name of the health check preset used to generate the report
  • Rule name: The rule that produced the result, for example Broken links or Duplicate ID.
  • Line number: The line in the file where the issue occurs.
  • Asset: The file in which the issue was found.

Select a result to open the corresponding file at the exact line where the issue persists.

NOTE
Broken link results open the file in Author mode. Duplicate ID and Schematron validation results open the file in Source mode.

Regenerate the report

After fixing an issue, select Regenerate in the toolbar to run the health check again and confirm the issue is resolved. In the Regenerate dialog that’s displayed, select the checks you want to include in the regenerated report.

NOTE
Health check reports are specific to the user who generated them. If multiple users generate a report for the same map, each user views their own results. Administrators, however, always have access to the latest report generated for the map.

Download the report

Select Download report to download the report in XLS format, with detailed information for every result.

Parent topic:Introduction to the Map Editor

recommendation-more-help
experience-manager-guides-help-product-guide