Peer Cross-References

Peer cross-references directly link to other topics or files in the content library.

Remember: We recommend structuring your maps in a way that guides users through the content without the need to excessively jump to different topics.

Overview

The element or topic that you directly link to must have a unique ID attribute assigned. Heretto CCMS enables you to assign the ID attributes to elements when you insert a link.

Figure 1. Peer Cross-Reference Operation.
The following example shows a peer cross reference that links from “Element B” in “Topic A” to “Topic B”.
Important: We do not recommend linking to elements in other topics because some publishing engines or publishing scenarios may produce unexpected results in the output.
Peer link

Use Cases

Consider using peer cross-references in the following scenarios:

  • When you want to refer to another topic.
    Figure 2. Peer Cross-Reference to Another Topic.
    The following PDF example shows that:
    • A peer cross-reference to the “Safety Warnings” topic is inserted in the note element.
    • The peer cross-references, when clicked, takes you to the “Safety Warnings” topic in the same map.
    • The link is print-friendly because the on page # text is automatically added to the local cross-reference.

      Where, # is the name of the page

    Peer link
  • When you want to create a process topic based on cross-references.
    Figure 3. Peer Cross-References in a Process Topic.
    The following example from the Content Portal shows that:
    • Peer cross-references are inserted in the prerequisite element, step elements, and postrequisite element.
    • Some of the links refer to topics in another map because the Content Portal can handle such a linking strategy.
    Peer link
  • When you want to link to a non-DITA file in the content library.
    Figure 4. Peer Cross-Reference to a File.
    The example from the Content Portal shows that:
    • A peer cross-reference to the “Sample_DOCX_Document.docx” file is inserted.
    • If you click the cross-reference, the “Sample_DOCX_Document.docx” downloads.
    Peer link to a file

Maintenance Guidelines

Peer cross-references require a moderate level of maintenance because they may limit topic reuse. If you do not want to limit topic reuse, consider doing any of the following:

Keep the following guidelines in mind when using peer cross-references:

  • If you link to a DITA topic, the title element of the topic is used as the link text. To reduce maintenance, we do not recommend entering custom link text.
  • Do not link to DITA maps as this may cause unexpected results in some outputs.
  • If you link to a non-DITA resource in the content library, the file name is used as the link text. If needed, enter custom generic link text.
  • Heretto CCMS prevents you from removing resources that are linked in other topics. When you attempt to move a resource to Trash, a warning appears. You need to remove the references to the resource before moving it to Trash.

Publishing Guidelines

Keep the following guidelines in mind when publishing content with peer cross-references:

  • We do not recommend linking to elements in other topics because some publishing engines or publishing scenarios may produce unexpected results in the output.
  • If you publish to a print-friendly output (for example, PDF), links may reference a page number.
  • If you publish to a print-friendly output (for example, PDF), ensure that the topic that you link to is included in the same map as the topic that you link from.
  • If you publish to a web output (for example, webhelps, or Content Portal), you can link to topics not included in the same map as the topic that you link from.

Insert Links to Topics or Files

Create a direct, inline link to another topic or file in your content library by using the cross-reference.

  1. Open a topic and place your cursor where you want to insert a link.
  2. In the toolbar, click the Insert Link icon.
  3. Click the Select file button.
  4. In the Library dialog, select a file and click the Link to File button.
    Tip: You can select topics or other files from your content library. For example, you can link to a PDF document or a DOCX file.
    You inserted a link to the topic or a file in your content library. The topic title is used as the link text. The link text changes automatically when you edit the linked topic title.
  5. If you linked to a non-DITA file, do the following:
    1. Click the link that you just inserted.
    2. In the Attributes tab, enter the file extension in both the format field and the type field.
      If you linked to a DOCX file, enter docx in the format field and in the type field.
  6. Optional: Change the link text by placing your cursor in the cross-reference and entering custom text.
    Remember: We don't recommend customizing the link text. You need to maintain and modify custom links each time the content changes and the link text is no longer relevant. You need to do that everywhere the link is used.
If you linked to non-DITA files, verify the links are properly rendered in the output.

Insert Links to Topic Elements

You create a direct inline link to an element in another topic by using the cross-reference.

Remember: Linking to elements in other topics is not a best practice. Instead of linking to an element in another topic, consider reusing that element.
  1. Open a topic and place your cursor where you want to insert a link.
  2. In the toolbar, click the Insert Link icon.
  3. Click the Select file button.
  4. In the Library dialog, select the file that contains the element that you want to link to.
  5. Select the element in another topic that you want to link to by doing the following:
    1. Click the Link Inside File (Select Target Element) button.
    2. In the Create/Edit Link dialog, select the element.
    3. From the list that appears, select the element.
    4. If prompted about the element ID, click OK and Save.
      Tip: Heretto CCMS generates ID values automatically but you can enter your own values. The ID values must be unique. Assigning customized values may boost consistency in your documentation.
    5. Click the Insert Content button.
  6. Optional: Change the link text by placing your cursor in the cross-reference and entering custom text.
    Remember: We don't recommend customizing the link text. You need to maintain and modify custom links each time the content changes and the link text is no longer relevant. You need to do that everywhere the link is used.
You inserted a cross-cross reference to the element in another topic.