Generating and using IDs for DITA elements
Generating IDs in DITA
ID values can be generated either on request or automatically for DITA elements.![]() |
Generate ID values on two paragraphs using the contextual menu |
![]() |
DITA -> ID Options menu |
The elements for which ID values will be generated automatically are specified using class attribute values, that means the automatic ID generation is specialization-aware, it will work not only for the elements defined as part of the DITA standard, but also for any custom specialization that defines its own specialized topics, tables, figures or lists.
![]() |
The ID Options dialog |
The ID value of an element can be manually added, removed or modified using the Attributes panel to access the id attribute of that element.
This action to generate ID values for DITA is part of the DITA framework configuration, so you can easily remove it or configure a different custom action to generate IDs. But in general, you should not need to change the ID generation because specific ID values should not matter that much.
Using IDs in DITA
Elements that have an ID value defined for their id attribute can be referred by that ID value from other parts of the DITA topic or from other topics, in order to create links or to reuse those elements. oXygen provides DITA specific actions to create DITA links and content references as part of the DITA framework. These default actions feature search and filter capabilities that should help you identify the element to point to, without the need to put semantic information in the ID value itself.Here it is an example of adding a content reference to a topic. Let's say we have this topic talking about inserting the SIM card in a phone. For that we need to remove the battery, insert the SIM and then add the battery. If we already have a task for removing the battery then we can reuse those steps instead of duplicating them. At the beginning of the steps element we need to add a content reference to refer to the steps from the task that describes how to remove the battery.
![]() |
A task that describes how to insert a SIM in a telephone |
![]() |
The insert content reference dialog |
Now, let's suppose we do not remember the task file name that talked about removing the battery, what can we do? We can use the drop-down from the action next to the URL field and choose Search for file.
![]() |
Trigger the Find Resource dialog |
Now oXygen will show the Find Resource dialog where you can search for content to identify the task that describes how to remove the battery. For example, once you start typing in the search field "rem", oXygen will show you the topics that match this prefix, sorted by relevance.
![]() |
The Find Resource dialog showing topics that match the search criteria |
The first match seems to be the one we want, if we look at the title, so we select it. oXygen will load that topic in the Insert Content Reference dialog and it will present all the defined IDs, showing a preview of each entry you select.
![]() |
Insert content reference displaying the available IDs in a topic |
Now, you can filter on the type of element that you want to refer using the Target Type combobox and you can also filter on content, topic ID and element ID using the Filter input. As the content is dynamically gathered from each element, it is a better practice to use this search functionality than to put part of the content in the ID value. If the content changes in time that ID value will be very difficult to maintain to keep it up-to-date with the changes made to content - either you leave an old ID value that does not match the updated content, or you change the ID value and then you need to change all the references to that ID.
We can filter for example to see only the task steps that contain "remove"
![]() |
Filtered IDs |
We see now the entry that we want, we preview it and choose to make a conref to this step.
![]() |
The topic contains a content reference to the identified step |
This functionality works similarly for links and helps you search on the content itself and not on the ID value to refer to an element.
The search functionality is available also directly in oXygen, both as a dialog and as a side view, for example if you use Window->Show View->Open/Find Resource then you will see the Open/Find Resource view that will help you search through all your resources, in content, in file paths and in reviews. The content search also supports XML elements, for example "title:battery" will find all topics that have the word battery in their title.
![]() |
The find resources view |
You can then open the topic you found, maybe generate IDs for elements that you want to reuse and then you can also drag and drop or copy and paste as link or paste as content reference to quickly link or reuse that content.