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 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 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 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 Heretto Deploy Portal), you can link to topics not included in the same map as the topic that you link from.