External Cross-References

External cross-references directly link to external resources like websites or documents hosted on servers external to your content library.

Overview

External links — Figure 1. External Cross-References Operation.
The following example shows that:
“xref A” links to a web page.
“xref B” links to a document on an external server.
“xref C” links to a file 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.

Use Cases

Consider using external cross-references in the following scenarios:

When you don't want to duplicate information from a website in your documentation.
Figure 2. External Cross-Reference to a Website.
The following example from the Content Portal shows an external link to https://www.dita-ot.org inserted in a note element.
When you want to link a document or a file hosted on a server external to the content library.
Figure 3. External Cross-Reference to a File.
The following example from the Content Portal shows an external link to https://docs.oasis-open.org/dita/dita/v1.3/dita-v1.3-part3-all-inclusive.pdf with the custom “DITA 1.3 Specification” link text.

Maintenance Guidelines

Depending on the link targets, external cross-references may require a considerable level of maintenance. Keep the following guidelines in mind when using external cross-references:

Link only to reliable external resources.
To reduce maintenance, if possible, insert a link to the home page of a website (for example, https://dita-ot.org) rather than a deep link (for example, https://www.dita-ot.org/dev/topics/pdf-customization-example.html).
If possible, link to external resources by using the Hypertext Transfer Protocol Secure (HTTPS) rather than the Hypertext Transfer Protocol (HTTP).

Publishing Guidelines

Keep these guidelines in mind when using external cross-references:

If you insert a link to an external resource, consider entering custom link text.
Do not enter custom link text if you plan to print hard copies of the document.

Insert Links to Websites

You create inline links that lead to supplementary information by using the cross-reference. For example, you can link to websites or external documents.

Open a topic and place your cursor where you want to insert a link.
Press Cmd > K (Mac) or Ctrl > K (Windows).
In the Link dialog, in the Link (href) field, enter the link address.
Enter https://www.heretto.com
Important: You need to include the protocol information in the external links that you insert. Include the https:// or http:// protocol name.
Click the Apply button or press Enter.
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.

Gretyl's Portal

Heretto Help