Inline Links

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. easyDITA 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.

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. easyDITA 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: easyDITA 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

Peer Cross-References

Peer cross-references directly link to other topics or files in the content library.

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

Overview

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

Figure 5. Peer Cross-Reference Operation.
The following example shows a peer cross reference that links from “Element B” in “Topic A” to “Topic B”.
Important: We do not recommend linking to elements in other topics because some publishing engines or publishing scenarios may produce unexpected results in the output.

Use Cases

Consider using peer cross-references in the following scenarios:

  • When you want to refer to another topic.
    Figure 6. Peer Cross-Reference to Another Topic.
    The following PDF example shows that:
    • A peer cross-reference to the “Safety Warnings” topic is inserted in the note element.
    • The peer cross-references, when clicked, takes you to the “Safety Warnings” topic in the same map.
    • 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

  • When you want to create a process topic based on cross-references.
    Figure 7. Peer Cross-References in a Process Topic.
    The following example from the Jorsek Portal shows that:
    • Peer cross-references are inserted in the prerequisite element, step elements, and postrequisite element.
    • Some of the links refer to topics in another map because the Jorsek Portal can handle such a linking strategy.
  • When you want to link to a non-DITA file in the content library.
    Figure 8. Peer Cross-Reference to a File in easyDITA.
    The example from the Jorsek Portal shows that:
    • A peer cross-reference to the “Sample_DOCX_Document.docx” file is inserted.
    • If you click the cross-reference, the “Sample_DOCX_Document.docx” downloads.

Maintenance Guidelines

Peer cross-references require a moderate level of maintenance because they may limit topic reuse. If you do not want to limit topic reuse, consider doing any of the following:

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

  • If you link to a DITA topic, the title element of the topic is used as the link text. To reduce maintenance, we do not recommend entering custom link text.
  • Do not link to DITA maps as this may cause unexpected results in some outputs.
  • If you link to a non-DITA resource in the content library, the file name is used as the link text. If needed, enter custom generic link text.
  • easyDITA prevents you from removing resources that are linked in other topics. When you attempt to move a resource to Trash, a warning appears. You need to remove the references to the resource before moving it to Trash.

Publishing Guidelines

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

  • We do not recommend linking to elements in other topics because some publishing engines or publishing scenarios may produce unexpected results in the output.
  • If you publish to a print-friendly output (for example, PDF), links may reference a page number.
  • If you publish to a print-friendly output (for example, PDF), ensure that the topic that you link to is included in the same map as the topic that you link from.
  • If you publish to a web output (for example, webhelps, or Jorsek Portal), you can link to topics not included in the same map as the topic that you link from.

Insert Links to Topics or Files

Create a direct, inline link to another topic or file in your content library by using the cross-reference.

  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. Click the Select file button.
  4. In the Library dialog, select a file and click the Link to File button.
    Tip: You can select topics or other files from your content library. For example, you can link to a PDF document or a DOCX file.
    You inserted a link to the topic or a file in your content library. The topic title is used as the link text. The link text changes automatically when you edit the linked topic title.
  5. If you linked to a non-DITA file, do the following:
    1. Click the link that you just inserted.
    2. Open the Attributes tab by clicking Attributes.
    3. In the Attributes tab, enter the file extension in both the format field and the type field.
      If you linked to a DOCX file, enter docx in the format field and in the type field.
  6. Optional: (Optional) Change the link text by placing your cursor in the cross-reference and entering custom text.
    Remember: We don't recommend customizing the link text. You need to maintain and modify custom links each time the content changes and the link text is no longer relevant. You need to do that everywhere the link is used.
If you linked to non-DITA files, verify the links are properly rendered in the output.

Insert Links to Topic Elements

You create a direct inline link to an element in another topic by using the cross-reference.

Remember: Linking to elements in other topics is not a best practice. Instead of linking to an element in another topic, consider reusing that element.
  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. Click the Select file button.
  4. In the Library dialog, select the file that contains the element that you want to link to.
  5. Select the element in another topic that you want to link to by doing the following:
    1. Click the Link Inside File (Select Target Element) button.
    2. In the Create/Edit Link dialog, select the element.
    3. From the list that appears, select the element.
    4. If prompted about the element ID, click OK and Save .
      Tip: easyDITA 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.
    5. Click the Insert Content button.
  6. Optional: (Optional) Change the link text by placing your cursor in the cross-reference and entering custom text.
    Remember: We don't recommend customizing the link text. You need to maintain and modify custom links each time the content changes and the link text is no longer relevant. You need to do that everywhere the link is used.
You inserted a cross-cross reference to the element in another topic.

External Cross-References

External cross-references directly link to external resources like websites or documents hosted on servers external to your content library.

Overview

Figure 9. External Cross-References Operation.
The following example shows that:
  • “xref A” links to a web page.
  • “xref B” links to a document on an external server.
  • “xref C” links to a file on an external server.
Important: Always ensure that the files that you link to are not malevolent. Be extra cautious when linking to executables like EXE or APP files.

Use Cases

Consider using external cross-references in the following scenarios:

  • When you don't want to duplicate information from a website in your documentation.
    Figure 10. External Cross-Reference to a Website.

    The following example from the Jorsek Portal shows an external link to https://www.dita-ot.org inserted in a note element.

  • When you want to link a document or a file hosted on a server external to the content library.
    Figure 11. External Cross-Reference to a File.

    The following example from the Jorsek Portal shows an external link to https://docs.oasis-open.org/dita/dita/v1.3/dita-v1.3-part3-all-inclusive.pdf with the custom “DITA 1.3 Specification” link text.

Maintenance Guidelines

Depending on the link targets, external cross-references may require a considerable level of maintenance. Keep the following guidelines in mind when using external cross-references:

Publishing Guidelines

Keep these guidelines in mind when using external cross-references:

  • If you insert a link to an external resource, consider entering custom link text.
  • Do not enter custom link text if you plan to print hard copies of the document.

Insert Links to Websites

You create inline links that lead to supplementary information by using the cross-reference. For example, you can link to websites or external documents.
  1. Open a topic and place your cursor where you want to insert a link.
  2. Press Cmd > K (Mac) or Ctrl > K (Windows).
  3. In the Link dialog, in the Link (href) field, enter the link address.
    Enter https://www.easydita.com
    Important: You need to include the protocol information in the external links that you insert. Include the https:// or http:// protocol name.
  4. Click the Apply button or press Enter.
  5. Optional: (Optional) Change the link text by placing your cursor in the cross-reference and entering custom text.
    Remember: We don't recommend customizing the link text. You need to maintain and modify custom links each time the content changes and the link text is no longer relevant. You need to do that everywhere the link is used.

Key References

You can indirectly link to topics in a map by using key references. You can consider key references as a reuse-friendly alternative to Peer Cross-References.

Overview

Instead of directly linking to a topic by using the exact file path, key references link to a key name assigned to a topic in map. In different maps, topics with key references can link to different topics without limiting topic reuse.

Figure 12. Key Reference Operation.
The following example shows that:
  • “Topic A” and “Topic C” are reused in “Map A” and “Map B”.
  • “Topic C” contains a key reference that links to the “sample_key” key
  • In “Map A”, “Topic C” links to “Topic B” because it has the “sample_key” value assigned
  • In “Map B”, “Topic C” links to “Topic D” because it has the “sample_key” value assigned

Use Cases

Consider using key references in the following scenarios:

  • When you want to reuse a topic in different maps and want to make the reused topic link to different topics.
    Figure 13. Keyref in the Topic Editor.

    The following example shows the linking illustrated in the Key Reference Operation diagram in the topic editor.





Maintenance Guidelines

Keep the following guidelines in mind when using key references:

  • The following easyDITA reports can help you manage key references:
    • Invalid Keyrefs Report checks for broken key references. This report lists keyrefs linking to key names that are not defined in the map.
    • Folder Keys Report identifies all the keys used in a specific folder and where they're used. This report is helpful if you're looking for ways to maximize your reuse opportunities.
  • Develop a key naming convention that is easy to implement and use.
  • Over a given map, we recommend using unique key values.

Publishing Guidelines

Keep the following guidelines in mind when publishing content with key references:

  • Your map won't publish if the key references in the map are not resolved.
  • If there are the same key values in a map, the key resolves to the first instance of that key name in the map.
  • If you publish to a print-friendly output (for example, PDF), links may reference a page number.

Assign Key Names

You must set a key name on a topicref element in a map to indirectly link to a topic.

  1. In the content library, hover over a map and click the Dock button.
  2. In the map editor, hover over the topic you want to assign a key name to.
    A quick list of icons shows.
  3. Click the Key icon.
  4. In the Keys field, enter a key name and click Update .
Insert a key reference. See Insert Key References.

Insert Key References

Create an indirect, inline link by inserting a key reference to a key name.

In a map, assign a key name to the topicref element that you want to indirectly link to. See Assign Key Names.
  1. In the content library, hover over a topic and click Open.
  2. In the toolbar, click the Insert Link icon.
  3. In the Link dialog, from the Link To drop-down menu, select Key (key reference) .
  4. Under the Keyref field, in the list, double-click a key.
    Remember: You must open a map or set map context to see available keys and resolve key references.

Set Element IDs

You can only link to the elements with an unique ID assigned.

Tip: If you link to elements by using the topic editor, easyDITA enables you to easily assign an automatically generated ID or custom ID. You don't need to assign IDs to elements that you want to link to firsthand.
You can assign IDs to elements before creating links to take control over the ID values naming convention and boost your documentation consistency. For example, if multiple users collaborate on the same content, they may have different ideas on how to name the ID values. To ensure that the values are consistent, you can assign the ID values beforehand.
  1. Open a topic and place your cursor in the element you want to create an unique ID for.
  2. Click the Attributes tab.
    Attributes tab screenshot.
  3. In the id field enter a unique ID.
    Tip: We recommend assigning an ID name related to the element so it's easy to identify later.
    Set the ID for a step element as stepDepressLever
    The Attributes tab with the id field filled in.