Local Cross-References

Local cross-references directly link to elements in the same topic.

Remember: We recommend structuring your topics in a way that guides users through the content without the need to excessively jump to different elements.

Overview

The element or topic that you directly link to must have a unique ID attribute assigned. Heretto CCMS enables you to assign the ID attributes to elements when you insert a link.

Figure 1. Local Cross-Reference Operation.

The following example shows a local cross-reference that links from “Element C” to “Element A” in the same topic.

Local link

Use Cases

Consider using local cross-references in the following scenarios:

  • When you want to mention a step element in another step element.
    Figure 2. Local Cross-Reference to a Step Element.
    The following PDF example shows that:
    • A local cross-reference to step 4 in step 5 is inserted.
    • The local cross-reference, when clicked, takes you to step 5.
    • The link is print-friendly because the on page # text is automatically added to the local cross-reference.

      Where, # is the name of the page

    Local link in the PDF output.
  • When you want refer to another element in a long topic.
    Figure 3. Local Cross Reference to a Section Element.
    The following PDF output example shows that:
    • A local cross-reference to the “Safety Features” section element is inserted.
    • The local cross-reference, when clicked, takes you to the “Safety Features” section.
    • The link is print-friendly because the on page # text is automatically added to the local cross-reference.

      Where, # is the name of the page

    Local link in the PDF output.

Maintenance Guidelines

Local cross-references require little maintenance and don't limit reuse because they don't link to peer topics or external resources.

Keep the following guidelines in mind when using local cross-references:

  • If you link to an element with a title element, the title element is used as the link text. To reduce maintenance, we recommend not entering custom link text, because it will be unique to only that link-instance.
  • If you link to an element with no title element, you enter the link text manually. To reduce maintenance, we recommend making the link text generic.
  • If you delete the linked content, you need to delete the link, too. Heretto CCMS informs you about broken links.

Publishing Guidelines

Keep the following guidelines in mind when publishing content with local cross-references:

  • If you publish to a print-friendly output (for example, PDF), local cross-references include a page number.
  • In some short topics, clicking a local cross-reference won't take you to another place in the topic because the topic is too short (for example, when your topic fits on a single PDF page). As a result, the link may seem broken.

Insert Local Links

Direct your users to another location in a topic by inserting a local link to an element in the same topic. For example, you can use local links to refer to a step element in a task topic or a section element in a concept topic.
  1. Open a topic and place your cursor where you want to insert a link.
  2. In the toolbar, click the Insert Link icon.
  3. In the Link dialog, from the Link To drop-down menu, select An Element in this file (Local link).
  4. Click Select Element.
  5. Select the element that you want to link to by doing the following:
    1. In the Create/Edit Link dialog, select the element.
    2. From the list that appears, select the element.
    3. If prompted about the element ID, click OK and Save.
      Tip: Heretto CCMS generates ID values automatically but you can enter your own values. The ID values must be unique. Assigning customized values may boost consistency in your documentation.
    4. Click the Insert Content button.
You inserted a local link to the element in the same topic.
Figure 4. Local Link in the PDF Output