Exercise 9: Working with links

In this exercise, you'll create navigational links between topics. Please keep in mind that this exercise will have you create far more links for the topics that you normally would in something that you are seriously developing for others to read.

In this exercise, you will use the topics and maps that you created in Exercises 6, 7, and 8.

You’ll become familiar with the following types of links:

  • Creating a link to another topic
  • Creating a link to a table
  • Creating a link to a definition list item
  • Creating a link to a web page
  • Creating a relationship table

Ensure that you read chapter 7 of the DITA Best Practices book.

Step 1: Create a link to another topic

In this first link example, use the recipe task that has the corresponding reference topic that contains the simple table.

  1. In the prerequisites section of the task, create a stem sentence in a paragraph that says something like: For a description of the list of ingredients, see
  2. Position your cursor after the word see, select DITA > Link > Cross Reference.
  3. In the Insert Reference window, click the folder icon next to URL, navigate to the topic, and click Open.
  4. In Target ID list, ensure that you click the title of the topic.
  5. Click OK to insert the link. (You do not need to enter anything within the <xref> element. The transform will use the title of the topic.)

Step 2: Create a link to a table

In the second link example, use the recipe task that has the corresponding reference topic that contains the table.

  1. In the prerequisites section of the task, create a stem sentence in a paragraph that says something like: For a description of the list of ingredients, see
  2. Position your cursor after the word see, select DITA > Link > Cross Reference.
  3. In the Insert Reference window, click the folder icon next to URL, navigate to the topic, and click Open.
  4. In Target ID list, ensure that you click the title of the table.
  5. Click OK to insert the link. (You do not need to enter anything within the <xref> element. The transform will use the title of the table.)

Note that you would also use this method for creating a link to a step, except that you would select the step from the Target ID list.

Step 3: Create a link to a definition item

In this example, use the recipe task that has the corresponding reference topic that contains a definition list.

  1. In the reference topic that contains the definition list, add an ID attribute to each <dlentry> element. The ID value should be unique in the topic, cannot contain spaces, and must be a single value.
  2. In the task topic, create a link for each ingredient in the prereq section to the corresponding <dlentry> element for that ingredient:
    1. Highlight the ingredient name.
    2. Select DITA > Link > Cross Reference.
    3. In the Insert Reference window, click the folder icon next to URL, navigate to the topic, and click Open.
    4. In Target ID list, ensure that you click the <dlentry> element for that ingredient.
    5. Click OK to insert the link.
  3. Repeat step 2 for each ingredient.

Step 4: Insert a link to a URL

In your concept topic, create a link to an external URL:

  1. Position your cursor where you want to insert a link.
  2. Select DITA > Link > Web Link.
  3. In the Input URL window, enter the address of the web page and click OK.

Step 5: Create a relationship table

In your map file, create a relationship table that links each recipe to its corresponding ingredient list:

  1. Position your cursor right before the ending tag for the map.
  2. Select DITA > Relationship Table > Insert Relationship table.
  3. In the Insert Relationship table, specify a 4-row, 2 column table.
  4. Click OK.
  5. In the first column of each row, select DITA > Insert > Insert Topic Reference to insert a topic reference to each of the task topics.
  6. In the second column of each row, insert a topic reference to the reference topic that contains the corresponding ingredient list.

Step 6: Create WebHelp rendition of the map

Create a WebHelp rendition of the map and topics. Verify that all of your links resolve correctly and appear as you expect.

Step 7: Zip your files and turn them in

Include the following updated files in a ZIP file ("yourName-Linking.zip") and upload it to BlackBoard:

  • concept topic from Assignment 6
  • 3 task topics from Assignment 6
  • 3 reference topics from Assignment 7
  • map file from Assignment 8