URL (External Links)
External links link to resources that exist outside of Heretto CCMS and are not part of the current document. They are most commonly used to link to websites or documents hosted on servers external to your CCMS. External links typically open in a separate window or tab to indicate that they are not part of the current documentation set.
Overview
- “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.
Always ensure that the files that you link to are not malicious. Be extra cautious when linking to program files like EXE or APP files.
Use Cases
Consider using external links in the following scenarios:
- When you don't want to duplicate information from a website in your documentation.
Figure 2. External Link to a Website. This example from the Heretto Portal shows an external link to https://www.dita-ot.org/dev/parameters/parameters_intro.html 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 Link to a File. This example from the Heretto Portal shows an external link to a PDF available at 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.
When you want to link an e-mail address that opens an e-mail application.
Figure 4. External Link to an E-mail Address. This example shows an external link added to an e-mail address. The link is clickable and opens an e-mail application.
Maintenance Guidelines
Depending on the link targets, external links may require a considerable level of maintenance. Keep the following guidelines in mind when using external links:
- 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 links:
- If you insert a link to an external resource, consider adding custom link text.
- Do not add custom link text if you plan to print hard copies of the document.