Related Links

The related-links element enables you to quickly add links to related information at the end of a topic.

Overview

By default the related-links element inserts at the end of the topic.

The following example shows that:
  • “link A” links to “Topic B” in the content library.
  • “link B” links to a non-DITA document in the content library.
  • “link C” links to a website.
  • “link D” links to a document hosted on an external server.
    Important: Always ensure that the files that you link to are not malicious. Be extra cautious when linking to executables like EXE or APP files.
Figure 1. Related Links Operation
Related links operation

Use Cases

Consider using the related-links element in the following situations:

  • When you want to link to DITA or non-DITA files in the content library that are not included in the map.
    Tip: When you want to link to a DITA file that is in the same map, we recommend using the Relationship Table Links because they do not limit topic reuse.
  • When you want to link to external resources like websites or documents on external servers.
Figure 2. Related Links.
The following example from the Heretto Deploy Portal shows that:
  • “Reference A” links to a DITA topic in the content library.
  • “Sample_Word_Document.docx” links to a Microsoft Word document in the content library. When you click it, the file downloads.
  • “DITA Open Toolkit Homepage” links to https://dita-ot.org/. The link has custom link text, and a description that is visible as a tooltip when you hover over the link.

Maintenance Guidelines

The related-links element require a moderate level of maintenance because they may limit topic reuse. If you do not want to limit topic reuse, consider using Relationship Table Links or Map Links.

Keep the following guidelines in mind when using related-links elements.
  • 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.
  • If you link to external resources, for example websites, you must add a link text manually. Remember to make it generic to avoid maintenance issues.

Publishing Guidelines

Keep the following guidelines in mind when publishing content with related-links elements:

  • Because the related-links element gathers links in one element at the end of a topic you can easily apply conditional profiling to this element or links inside it so that links are included, for example, only in online outputs.

    For more information, see Conditional Processing Strategies.

  • 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.
  • The related links are usually displayed at the end of the topic. Some web-like outputs (for example, webhelps) may display them in a separate navigation pane.
  • 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.