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 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.
- 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.
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 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.
Insert Links to Topic Elements
You create a direct inline link to an element in another topic by using the cross-reference.