Cross references (<xref>)

Cross-references are hyper-links to other locations, in the same page or to another page.

Cross references created with an <xref> element create a HTML link in the published output. There are two types of DITA cross references:

  • href is a link to a specific topic in the file system. Most of our cross-reference links use this format.

  • keyref is an indirect link to a topic based on a key value assigned in the map that directly loads the topic. Use this when you need to link to a topic in another branch.

hrefkeyref
Target selectionThe target file can be selected via the GUI.The key can be selected via the GUI when a map with the key is assigned to the Context map in the editor.
Link text while editing Target title appears in the editor and in the published link.Same, except in the editor the title appears in the link text only when a map with the key is assigned to the Context map in the editor.
Target existence while editingThe target file must exist in the (same branch as) file system, or the source topic will report a broken link error.The target key/file does not have to exist.
Target existence while publishingThe target must be referenced in a map that is included in the publish-job or there will be a broken-link error.The key must be referenced in a map that is included in the publish-job or there will be a missing-key error.
BranchesThe target must be in the same branchThe Target does not have to be in the branch
Peer scopeCan use a peer scope to reference target in another branch, but cannot pull in title from targetN/A (peer not needed)
Broken linksHappen when the target is not in the published sitemap/map-tree. Happen when the key is not in the published sitemap/map-tree.
Target resourceIdOnly when the scope="peer"N/A
Deep links (to elements in a topic)Can link to an element in the topic that contains a <title> element.N/A

Cross reference guidelines

When creating cross reference, follow these guidelines.

  • By default, the text shown in the published link automatically comes from the target element.

    Target elementLink text
    Topic, section, table, or figureThe target element's <title> value. This will be shown in the Heretto Content Editor.
    List item (ordered) or step itemThe target elements step number

  • When the target element does not have an associated <title>, provide descriptive text for the link label.

    • Do not say "here" for the link text. For example, "[Click here]" or "For information, see [here]."

  • For external links the text should be either

    • The title of the target page, such as <xref href='https://www.medallia.com>Medallia, Inc.</xref>

    • A shortened URL to the target page, such as <xref href='https://www.medallia.com>Medallia.com</xref>

    • (default) The complete URL to the target page, such as <xref href='https://www.medallia.com/>

  • Do not use an href link to a topic in another branch; always use a keyref for links to other branches.

Href to a topic

A simple href to a topic links to a topic in the same branch as the source topic.

Warning: Do not link to a topic in a different branch from the source topic, or the link will break when published.

To create a simple href to a topic:

  1. Press Command-k.
  2. Choose Link to: File in Heretto.
  3. For the Href, select the target file.
  4. Choose Link to File.

The result looks similar to this: Tips for working in Heretto

And the source looks similar to this:

<xref href="How_tos.dita"></xref>

Deep links are cross references to titled elements contained in a topic. They can be in the same topic, or a different topic. Generally deep links behave the same as Href to a topic, described above.

Same topic

To create a deep link in the same topic:

  1. Press Command-k.
  2. Choose Link to: An element in this file (Local link).
  3. For the Element ID, select the target.

The result looks similar to this: Href to a topic

And the source looks similar to this:

<xref scope="local" href="#topic-7485/href-to-topic"></xref>

Different topic

To create a deep link in a different topic:

  1. Press Command-k.
  2. Choose Link to: File in Heretto.
  3. For the Href, select the target file.
  4. Choose Link Inside File (Select Target Element).
  5. Choose the existing from the right-side of the dialog or,
    When the target section does not already have an ID:
    1. In the left-side of the dialog, scroll, locate, and click the target title element.
    2. From the popup list that appears, click the element that contains title, such as a <section> or <table>.
    3. Provide a new ID for the element.

      Keep it simple and try to make it easy to locate in a list (don't have all IDs begin with the same text because the ID value can be truncated in some list displays.)

    4. Choose the new ID from the right-side of the dialog.

The result looks similar to this: Notes tests

And the source looks similar to this:

<xref href="notesTest.dita#topic-4096/section-note-tests"></xref>

Keyref to a topic

A keyref cross-reference links to a topic based on a key value assigned in the map that references the topic.

The main reason to use a keyref based cross-reference is to link to a topic that is in another branch, but which is published from the same <sitemap>. For example, each product in the doc portal has its own unique branch, but all are referenced in the same portal sitemap. As long as the key is available somewhere in the sitemap tree, the link is resolved correctly.

Consider this <topicref> from a map. Notice the keys attribute:

<topicref href="How_tos.dita" keys="heretto-tips"/>

At publishing time a keyref cross-reference to the heretto-tips key resolves to the How_tos.dita DITA topic.

Note: One drawback of the keyref approach is the key is defined in a map, which makes it a little hard to track down. (But does allow different (publish) maps to point to different topics for the same key value; something we do not do at Medallia.) An alternative method is to use a Peer link to a resourceId. See below for details.

To create a keyref to a topic:

  1. (If not already done) Add the key in the target map before editing the topic that will contain the cross reference.

    1. Open the map for editing.

    2. In the map hierarchy, click the key icon for the target topic and enter the key. Topics that have keys show the key value in the map.Map opened for editing with the key editor open and showing two topics with existing key values

  2. In the topic that will have the cross reference, first set the Context (upper left corner) to be the target map (that defines the key value).

    Shows the Context selector with an arrow pointing to the 'Select a context map' link

  3. In the source topic, press Command-k.
  4. Choose Link to: Key (key reference).
  5. For the Keyref, select the key from the list).

    Screen capture showing the keyref list for the current context map

The result looks similar to this: Tips for working in Heretto. (When the Context is set to the map, the link label is the title from the target; otherwise, it is the key value.)

The source looks similar to this:

<xref keyref="heretto-tips"></xref>

Href to an external topic

Link to a web site outside of the doc portal.

To create a simple href to an external topic:

  1. Press Command-k.
  2. Choose Link to: A URL (External link).
  3. For the Link (href), enter the URL to the target site; include the HTTP specifier like https://.

The result looks similar to this: https://www.medallia.com

The source looks similar to this (note the scope attribute):

<xref scope="external" href="https://www.medallia.com"></xref>
For external links the link text should be either

  • The title of the target page, such as <xref href='https://www.medallia.com>Medallia, Inc.</xref>

  • A shortened URL to the target page, such as <xref href='https://www.medallia.com>Medallia.com</xref>

  • (default) The complete URL to the target page, such as <xref href='https://www.medallia.com/>

A link to a resourceId is an alternative to the Keyref to a topic described above. Many topics have resourceIds as a way of identifying the topic to bookmarks and context-sensitive help links.

  • The advantage of a resourceId is the ID is specified in the topic, rather than in a map.

  • The biggest disadvantage is the title cannot be automatically inserted in the link test; you must manually provide a label or the URL will display instead.

Note: There is a bug in the current (September 2023) portal instance that causes peer links to open in a new browser tab or window; rather than the current window/tab.

To create a simple href to a topic:

  1. Press Command-k.
  2. Choose Link to: A URL (Peer link).
  3. For the Peer link (href), enter /?resourceId= followed by the resourceId from the target topic..

The result looks similar to this: Sampling triggers

The source looks similar to this:

<xref href="/?resourceId=mec-surveying-sampling-triggers" scope="peer">Sampling triggers</xref>