Overview

Peer links enable you to link to content that is part of your current documentation set but might not be available at build time. An example of a peer link is a link to a resource in a contextual help when that resource is not present in Heretto or online, but is part of your documentation set. For example, this peer link <xref scope="peer" href="?resourceId=customer-support">Customer Support</xref> links to a resource ID specified as ?resourceId=customer-support.

The name peer link comes from the scope attribute value peer. When you add a peer link, Heretto automatically sets the scope attribute to peer.

Peer links resolve once you publish your content and deploy it to its final destination. Peer links typically open in the same window or tab to indicate that they are part of the current documentation set.

Use Cases

Consider using peer links in the following scenarios:

• When you want to link to a resource that is not part of your current documentation set but that will be available when you deploy your content to its final destination, for example, a contextual help or a resource that is behind a firewall or inside a virtual private network (VPN).

Maintenance Guidelines

Depending on the link targets, peer links may require a considerable level of maintenance. Keep the following guidelines in mind when using peer links:

• Add link text only when you link to a resource that resolves with no link text.

• If you link to resource IDs, avoid updating IDs to avoid broken links.

Publishing Guidelines

Keep these guidelines in mind when using peer links:

• Heretto doesn't flag peer links in publishing logs as they are expected not to resolve at publishing time.

• When you publish content that contains peer links in Heretto, your peer links are visually presented as links, for example, they are highlighted blue, but they are not clickable, or they are clickable but they take you to the beginning of the document.

• If you need to publish your content that contains peer links to outputs that can't have access to the resources those peer links refer to, for example, a PDF, consider using conditional processing to filter out the link and its related content from the PDF output. Otherwise, your peer links will publish as broken links.

• Once you deploy your documentation set to its final destination, for example, a contextual help, verify that all your peer links resolve correctly.