DITA Maps Preferences

To access the DITA Maps preferences page, open the Preferences dialog box and go to DITA > Maps. This preferences page includes the following options:

Expand references to other maps when opening a map in Author mode: Enabling this option will improve performance (decrease the loading time) when opening maps in Author mode (particularly maps that contain a large amount of submaps). This option is disabled by default.
Note: You must close and reopen the map to see the effects of enabling/disabling this option.

DITA Maps Manager section

Only display items related to currently open maps in the Context drop-down list: If selected, only the currently open maps and contexts that are relevant to the currently open maps are displayed in the Context map drop-down menu in the DITA Maps Manager. This is helpful if you are working with multiple DITA-OT projects and DITA maps set as Main Files since it helps you narrow down the relevant contexts.
Prefer using the navigation title for rendering topic references: If selected and there is a @navtitle attribute set on a <topicref>, then the @navtitle is used to render the title of the topic in the DITA Maps Manager.
Allow referenced submaps to be edited: If selected, all DITA maps referenced directly or indirectly in a DITA map that is open in the DITA Maps Manager view will be fully editable. You will be able to add new topic references, modify properties, and move topic references from one submap to another. Saving the main DITA map will also save the contents of the modified submaps.
Attention: The documents must be reopened to apply a change to this option.
Local files only: If selected, only submaps that are located on local disk drives will be editable. As for maps located in remote locations (e.g. content management systems), the save operation might not work on all submaps. This checkbox is selected by default.

Inserting Topic References section

Always set values for the following attributes

Allows you to specify that when inserting a topic reference (using the Insert Reference dialog box and Edit Properties dialog box), the values for certain attributes will always be automatically populated with a detected value (based on the specifications), even if it is the same as the default value. You can choose to always populate the values for the following attributes:

Format - If selected, the @format attribute will always be automatically populated with a detected value.
Scope - If selected, the @scope attribute will always be automatically populated with a detected value.
Type - If selected, the @type attribute will always be automatically populated with a detected value.
Navigation title - If selected, the @navtitle attribute will always be automatically populated with a detected value.

Use the file name as the value of the "keys" attribute

If selected, when inserting a topic reference into a map, the file name will be used as the value of the @keys attribute for the new <topicref>. The key is not defined on the <topicref> for references to DITA maps. This option has a slightly different effect depending on the method used for inserting the topic reference:

Drag/Drop or Copy/Paste in the DITA Maps Manager - If you drag or copy a resource from another view (or outside Oxygen XML Author Eclipse plugin) and drop or paste it into the DITA Maps Manager and a key is already defined for that resource, a @keyref attribute will be inserted instead. This even works for two consecutive drag/drop or copy/paste operations without saving the file and it works for multiple selections of topic references.
Drag/Drop or Copy/Paste in a Map opened in Author Mode - If you drag or copy a resource from another view (or outside Oxygen XML Author Eclipse plugin) and drop or paste it into a map that is open in Author mode and a key is already defined for that resource, a @keyref attribute will be inserted instead.
Restriction: In this particular scenario, if you perform two identical, consecutive drag/drop or copy/paste operations without saving the file between operations, the value of the @keys attribute will be the same for both inserted topic references. The workaround for this limitation is to simply save the map after each drag/drop or copy/paste operation.
Using the Fast Create Topics or Duplicate Actions - If you use the Fast Create Topics feature or Duplicate action to insert topic references, the newly created <topicref> elements will contain the @keys attribute with its value set depending on the file name.
Using the Insert Topic Reference Dialog Box from the DITA Maps Manager - If you use an action in the DITA Maps Manager to insert topic references (e.g. Append Child > Reference), a @keys attribute will be set for each inserted topic reference and the value depends on the file name. You can see the value in the Define keys field from the Keys tab of the Insert Reference dialog box and you can change it.

Note: This option also has an effect on image references. When inserting a reference to an image in a DITA map and this option is selected, a <keydef> element is created if it is allowed by the schema. If it is not allowed (or this option is deselected), a specific topic reference element is created with the value of the @processing-role attribute set to resource-only.

Prefer adding key references to already referenced resources

If selected, when a topic reference is inserted into a map and a key is already defined for that resource, a @keyref attribute is inserted for the new <topicref>. If not selected, an @href attribute is inserted instead.

Dynamic conversion of specific non-DITA resources

If selected (default), non-DITA documents are dynamically converted to DITA when they are chosen in the Insert Reference dialog box and the IDs from the resulting DITA content are presented in the dialog box. If not selected, non-DITA documents (Word, Excel, Markdown, OpenAPI, and HTML) are not dynamically converted when they are chosen in the dialog box.