External Cross-References

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


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.
External links

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.

    External link to a website
  • 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.

    External link to a file

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:

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.
  1. Open a topic and place your cursor where you want to insert a link.
  2. Press Cmd > K (Mac) or Ctrl > K (Windows).
  3. 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.
  4. Click the Apply button or press Enter.
  5. 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.