A topic is inserted into the topic map using the <topicref> element. This element has an attribute href that points to the topics's GUID identifier. A simplification of the element looks like this:

<topicref href="GUID"></topicref>

There are two ways to insert the topic:

You can use the editor's dialogue box
You can manually insert a <topicref> element and then copy the object's GUID into the href attribute.

Procedure

Using the editor's dialogue box:
1. Place the cursor where you want to insert the topic.
2. From the editor's main menu, select DITA ➜ Insert topic reference.
3. In the dialogue box that opens, set Reference type to Topic Reference.
4. On the right side of the dialog, click the green icon to open the database.
5. In the database, locate the topic you want to insert.
6. Once you find it, double-click it to select it.
  
  The dialogue box reopens.
7. Click Insert and close.
Inserting a <topicref> element manually:
1. Find the topic you want to insert, and copy the GUID identifier for it.
  
  You can retrieve the GUID identifier from the object's Properties dialog. If you've put the GUID identifier in a comment at the top of the topic, you can retrieve it from a preview. You can also open the topic to have a look.
2. Place the cursor where you want to insert the topic.
3. Press the Enter key on your keyboard and select <topicref> from the shortcut menu.
4. Click the start tag in the <topicref> element, then press Alt-Enter on your keyboard to open the attributes dialogue box.
5. Set name to href.
6. Copy the GUID identifier into the Value box.
7. Click OK.
Note that the <topicref> element now appears in your topic map with the object's GUID identifier shown.
Recommended: Do the following:
1. Click the small icon that appears on the left side of the <topicref> element.
  
  The topic opens in the editor.
  
  Verify that you have inserted the correct topic.
2. Copy the two comments you entered when you created the topic, and paste them above the <topicref> element in the topic map.
Like this:
```
<comment>The topic's metadata title</comment>
<comment>The topic's GUID identifier</comment>
<topicref href="GUID">(The topic's GUID identifier is shown here)</topicref>
```
The comments will always tell you which topic you have inserted. If you need to copy the <topicref> element to another location, remember to include the two comments.

Related concepts

About DITA topics

Topic content and structure

All external links open in a new window. I take no responsibility for information on external websites, even if I have linked to them. Please report links that do not work.

The information on this page represents my personal opinions and my understanding of the topic being described. Feel free to link to the page, but do not copy large parts of the content without permission. I take no responsibility for any errors, misunderstandings or missing information. I also take no responsibility for any mistakes you may make or cause as a result of incorrect or missing information. You are welcome to contribute with comments, relevant experiences or additional information. See Editor and contact information.

2022-11-29