Table of Contents
User Guide
Cross-References
Cross-References
Cross-references (xrefs) are direct links to other files or external resources.
Inserting a Link to a File
You can create an inline link to a topic or map in the Content Library by using a cross-reference (XRef) link. Cross-references are direct links that lead you to supplementary information.
Inserting a Link to a Website or PDF
Cross-references (XRef) are inline links that lead you to supplementary information. Create a cross-reference link to an external source like a website or PDF.
Cross-References

Cross-references (xrefs) are direct links to other files or external resources.
section

Definition

Cross-references enable you to directly link to another file in easyDITA or to external resources, such as websites or PDFs.
section

Example

section

Maintenance Considerations

When you use cross references to link to other DITA resources, easyDITA manages the reference for you so if the topic is moved or renamed, the link will still work. Links will not work if the referenced topic is removed from your Content Library , but easyDITA will prevent you from doing so. When you attempt to move a file to the Trash , a warning will display if that file is referenced by any other files. You must remove the reference before moving the file to the trash. 
Also, any files you link to with an cross reference must be included in your publication map. If you fail to include a referenced topic in a map, the map will still publish, but the link won’t work.easyDITA
You can use the varsReports/reportLinkOutOfMapScope in easyDITA to check for any referenced topics that are not included in your map. As an administrator, you can access this in the Reports interface.
Before inserting links to external resources, such as web pages, you should consider the source you’re linking to. Will that web page be there in a year or more? Is it a reliable source? When you link to external resources, you’re relying on it being there in the future so you must consider whether it’s a reliable source.
section

Publishing Considerations

When using cross references, you should determine a consistent method of inserting links inline and naming your links. We recommend maintaining a consistent presentation of inline links throughout your documentation. For example, you might use the phrase:
“For more information, see _____.”
When determining the naming structure for you links, you have two options. easyDITA can manage link names for you or you can insert your own link text. If you insert a link to another DITA resource, the link will automatically display the title of the resource unless you manually change the link text. If you insert a link to an external resource, you should always insert your own link text. 
When you use cross-reference links to reference an external resource, you should consider the medium for publishing. For example, a link won’t be helpful to the reader if the document is delivered in print. You may want to put these links in their own paragraph or phrase element and apply conditional processing to that element so you can remove the links from certain publishes.
Inserting a Link to a File

You can create an inline link to a topic or map in the Content Library by using a cross-reference (XRef) link. Cross-references are direct links that lead you to supplementary information.
Tip:We recommend using key references (keyrefs) instead of using cross-references to create a link to a topic. For more information, see Key References. If you’re trying to link to an external source, see Inserting a Link to a Website or PDF.

  1. In the Content Manager , open a topic and place your cursor where you want to insert a link.

    Step Information
    Note:By default, when you insert a XRef link, the topic’s title is used as the link text. This is rendered by easyDITA, so you don’t need to enter any text for the link.

  2. Click Link -> Xref .

    Expected Result
    An empty link element is inserted. The text is underlined and blue.
  3. Click Edit.

    Expected Result
    The Select Link window displays.
  4. Navigate to and select the file, and then click Select .

    Expected Result
    The link is inserted and the “XRef Link” placeholder is replaced with the topic’s title.
result

You inserted a direct link to another topic.

Note:You can change the link text by placing your cursor in the Xref link and entering new text. We do not recommend doing this because it makes link management difficult and tedious (E.g. the topic name changes). Custom link texts need to be maintained and modified each time the content changes and the link text is no longer relevant. This same change also has to be made every where the link is used.
Inserting a Link to a Website or PDF

Cross-references (XRef) are inline links that lead you to supplementary information. Create a cross-reference link to an external source like a website or PDF.
  1. In the Content Manager , open a topic and place your cursor where you want to insert a link.
  2. Click Link -> Xref .

    Expected Result
    An empty link element is inserted. The text is underlined and blue.
  3. Click Properties .

    Expected Result
    The Properties Pane displays. The properties for the XRef link display at the top.

  4. In the Source (href) field, enter the URL for the external source.

    Step Information
    The URL must contain http://. For example, http://www.google.com

    Source (href) field

  5. In the Scope drop-down menu, select external.
  6. In the Format field, enter the format of file expected at the link. For example, html or pdf.
  7. In the XRef Link element, enter text for the link.

    Example

result

You inserted a link to an external source.