Peer Cross-References
Peer cross-references directly link to other topics or files in the content library.
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.
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
- 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.
- 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.
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:
- Inserting a key reference. See Key References.
- Inserting a relationship table. See Relationship Table Links.
- Reusing elements. See Element Reuse.
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.