URL (Peer Links)

Create peer links to link content that is not available at build (publishing) time. In Heretto CCMS, peer links are handled as links with a delayed resolution. In Heretto Portal, they are just a link to content like any link to a topic.

Peer links enable you to link to content that is part of your current documentation set but might not be available at build time. For example:

  • The Preferences window in your product has a help button with a specific ID. A topic in the CCMS that documents options in that window uses a resourceid element with that same ID to map itself to the window. Because the UI isn't part of the build, a peer link preserves that connection so the right topic opens when the user clicks help.

  • Your troubleshooting guide links to an API reference that another team maintains and publishes on its own schedule. The topic is part of your documentation set, but not part of your build.

Peer links use the DITA resourceid element as an identifier that resolves the link. 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, where the ID value is customer-support.

To specify the ID on the resourceid element you can use the id attribute as well as the DITA 1.3 appid and appname attributes.

Note:

Currently, the href attribute of a peer link supports both resourceId and resource_id. However, resource_id is deprecated and will eventually be discontinued. We recommend using only resourceId.

The name peer link comes from the scope="peer" attribute that is required for this link type. When you add a peer link, the CCMS 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.

Figure 1. Peer Links Operation.

This example shows that:

  • xref A links to resource A in a context-sensitive help

  • xref B links to resource A inside a virtual private network (VPN)
Peer links are useful when you need to link resources that are not available at build time, for example, resources in a virtual private network (VPN)

Consider using peer links in these scenarios:

  • When you want to link to a resource that is not part of your current documentation set but will be available when you deploy your content to its final destination, for example, a context-sensitive 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 context-sensitive help, verify that all your peer links resolve correctly.

Insert Peer Links

You can create links to resources that are not available in Heretto CCMS or online. For example, you can link to resources available in a context-sensitive help or inside a virtual private network (VPN).
  1. Open a topic and place your cursor where you want to insert a link.
  2. In the Content Editor toolbar, click Insert Link .
  3. In the Link dialog, from the Link To drop-down menu, select URL (Peer link) .
  4. In the Link dialog, in the Link (href) field, enter the link address.
    Enter a resource ID: /?resourceId=customer-support
    Note:

    Currently, the href attribute of a peer link supports both resourceId and resource_id. However, resource_id is deprecated and will eventually be discontinued. We recommend using only resourceId.

  5. Click the Apply button or press Enter.
  6. Change the link text by placing your cursor in the link and entering custom text, like Customer Support.

    If you provide no link text, the href attribute value is used as link text.

You added a peer link that looks like this: <xref scope="peer" href="/?resourceId=customer-support">Customer Support</xref>. It links to a resource that is not part of your current documentation set and so can't be resolved before your content is published and deployed to its final destination.

Last updated: April 29, 2026