Linking Strategies

easyDITA provides you with different ways to link content. Proper linking can help readers navigate individual documents and your documentation portal.

Inline Links Overview

Inline links enable you to insert references to other content in the context of topic elements.

Considerations

Keep the following considerations in mind when inserting inline links:

  • Inline links may tempt readers to click the link and navigate away from the current content before they finish reading it.
  • We recommend maintaining a consistent introduction of inline links throughout your documentation. For example, you can introduce links by using the following phrase: For more information, see link.
  • Various publishing engines and publishing scenarios may handle links differently. Always ensure that the links are resolved and rendered as expected in the output.

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.

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 4. 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 5. 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 6. 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 7. 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.

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 8. 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 9. 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 10. 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.

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 11. 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 12. 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.

Block Links Overview

Block links enable you to insert references to other content in the context of entire topics. Typical block links are relationship table links, related links, and map links.

Considerations

Keep the following considerations in mind when inserting block links:

  • In contrast to inline links, block links are placed at the end of a given topic. That may prevent readers from navigating away from the topic before finishing reading it.
  • In contrast to direct inline links, block links do not limit topic reuse.
  • Various publishing engines and publishing scenarios may handle links differently. Always ensure that the links are resolved and rendered as expected in the output.

Relationship Table Links

Relationship tables enable you to link related topics in a map.

Default Relationship Table Overview

You begin a relationship table by adding a reltable element to a map. To enable linking between the particular topics in a map, you insert the topicref elements into the appropriate relationship table cells. easyDITA enables you to perform these actions by using an intuitive graphical interface.

Figure 13. Relationship Table Operation.

The following example shows that the reltable element links the “Concept A”, “Task A”, “Reference A”, “Reference B”, and “Reference C” topics together in the “Map A”. The topics are not linked outside the map.

The default relationship table layout includes three columns that correspond to the following topic types:

  • concept topic
  • task topic
  • reference topic

By default, relationship tables handle linking in the following way:

  • Topics in a given table row link to each other
  • Topics in the same table cell don't link to each other

In the following example “Concept A” links to “Task A”, “Reference A”, “Reference B”, and “Reference C” because these topics are in the same table row. The reference topics link to “Concept A” and “Task A” but don't link to each other because they are in the same relationship table cell.

Figure 14. Default Relationship Table
Default relationship table example in easyDITA.

The following PDF output examples illustrate the default linking settings of a relationship table.

Figure 15. Default Relationship Table Linking (Concept A)
Relationship table linking example in the PDF output.
Figure 16. Default Relationship Table Linking (Task A)
Relationship table linking example in the PDF output.
Figure 17. Default Relationship Table Linking (References)
Relationship table linking example in the PDF output.

Customized Relationship Table Overview

Relationship tables are highly customizable. The following attributes enable you to adjust the most useful linking settings in your relationship tables.

collection-type attribute
Assigning the family value to the collection-type attribute of the relcell element enables linking between topics inserted in the same relationship table cell.

In the following example, the cell that contains the concept topics is configured to enable cell linking.

Figure 18. Cell Linking in a Relationship Table
A relationship table with cell linking enabled in easyDITA.

The following PDF output example illustrates linking between “Reference A”, “Reference B”, and “Reference C” inserted in the same relationship table cell.

Figure 19. Cell Linking Example
Cell linking example in the PDF output.
linking attribute

Assigning the sourceonly value to the linking attribute of the topicref element modifies the topic linking in the following way:

  • Prevents other topics from linking to the topic

  • Allows the topic to link to other topics

Assigning the targetonly value to the linking attribute of the topicref element modifies the topic linking in the following way:

  • Allows other topics to link to the topic

  • Prevents the topic from linking to other topics

In the following example, “Concept A” links to other topics in the same relationship table row but other topics don't link to “Concept A”.

Figure 20. Sourceonly Linking in a Relationship Table
A relationship table containing a sourceonly linking topic in easyDITA.

The following PDF output examples illustrate “Concept A” with linking attribute set to targetonly value.

Figure 21. Sourceonly Linking Example (Concept A)
Sourceonly linking example in the PDF output.
Figure 22. Sourceonly Linking Example (Task A)
Sourceonly linking example in the PDF output.

In the following example, “Task A” doesn't link to other topics in the same relationship table row but other topics link to “Task A”.

Figure 23. Targetonly Linking in a Relationship Table
A relationship table containing a targetonly linking topic in easyDITA.

The following PDF output example illustrates “Concept A” that links to “Task A” with linking attribute set to the targetonly value. “Task A” does not link to other topics in the same relationship table row.

Figure 24. Targetonly Linking Example
Sourceonly linking example in the PDF output.

Use Cases

Consider using relationship tables if you want to reuse topics in multiple maps or reduce the number of dependencies between topics.

Figure 25. Relationship Table Links.
The following PDF output example shows that:
  • The following topics are linked together in the “Classic Toaster User Guide” map: “Safety Warnings”, “Cleaning the Toaster”, and “Specifications”.
  • The links are placed at the end of each linked topic in the “Related topic_type” section.

    Where, topic_type is the type of a DITA topic that you link to.









Maintenance Considerations

Keep the following considerations in mind when working with relationship tables:

  • Relationship tables require little maintenance because every link is in the reltable map element.
  • easyDITA includes an editor that enables you to easily manage linking in relationship tables by dragging and dropping topics into the appropriate table columns.
  • Relationship tables do not limit topic reuse because you link topics on a map level.

  • You can add multiple relationship tables to a map. It is useful if you plan to maintain a large number of relationship table links.

Publishing Considerations

Keep the following considerations in mind when publishing maps with relationship tables:

  • Relationship table links are published at the end of a topic in the “Related Links” section.
  • If you publish to a print-friendly output (for example, PDF), links may reference a page number.
  • Relationship table links resolve at publish by populating the link text with topic titles.

Related Links

The related-links element enables you to quickly add links to related information at the end of a topic.

Overview

By default the related-links element inserts at the end of the topic.

The following example shows that:
  • “link A” links to “Topic B” in the content library.
  • “link B” links to a non-DITA document in the content library.
  • “link C” links to a website.
  • “link D” links to a document hosted 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.
Figure 26. Related Links Operation

Use Cases

Consider using the related-links element in the following situations:

  • When you want to link to DITA or non-DITA files in the content library that are not included in the map.
    Tip: When you want to link to a DITA file that is in the same map, we recommend using the Relationship Table Links because they do not limit topic reuse.
  • When you want to link to external resources like websites or documents on external servers.
Figure 27. Related Links.
The following example from the Jorsek Portal shows that:
  • “Reference A” links to a DITA topic in the content library.
  • “Sample_Word_Document.docx” links to a Microsoft Word document in the content library. When you click it, the file downloads.
  • “DITA Open Toolkit Homepage” links to https://dita-ot.org/. The link has custom link text, and a description that is visible as a tooltip when you hover over the link.

Maintenance Guidelines

The related-links element require a moderate level of maintenance because they may limit topic reuse. If you do not want to limit topic reuse, consider using Relationship Table Links or Map Links.

Keep the following guidelines in mind when using related-links elements.
  • 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.
  • If you link to external resources, for example websites, you must add a link text manually. Remember to make it generic to avoid maintenance issues.

Publishing Guidelines

Keep the following guidelines in mind when publishing content with related-links elements:

  • Because the related-links element gathers links in one element at the end of a topic you can easily apply conditional profiling to this element or links inside it so that links are included, for example, only in online outputs.

    For more information, see Conditional Processing Strategies.

  • 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.
  • The related links are usually displayed at the end of the topic. Some web-like outputs (for example, webhelps) may display them in a separate navigation pane.
  • 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.

Map Links

Map links enable you to link topics in a map based on their parent-children relationship in the map structure.

Overview

You create map links by using the appropriate map structure and the collection-type attribute.

The collection-type attribute can take the following values:

sequence value
Generates an ordered list of links from parent to children. The order of links is the same as the order of topics in the map.
unordered value
Generates an unordered list of links from parent to children. The order of links is the same as the order of topics in the map.
family value
Generates an unordered list of links from parent to children and from sibling to sibling. The order of links is the same as the order of topics in the map.
choice value
Uncommon and typically used in custom outputs that enable the user to select one child topic to continue. In most cases, it is rendered in the same way as the unordered value.
Figure 28. Map Links Operation.
The following example shows that:
  • The “Task B” is a process topic with the collection-type attribute set to the sequence value.
  • “Task B” will link to “Task C”. “Task D”, and “Task E” in the output.
  • The linked topics will not link to each other outside the map.

Use Cases

Consider using map links in the following situations:

  • When you want to create a process topic based on map links
    Figure 29. Process Map Structure.
    The following example shows that:
    • There are three procedures appended under the “Process A” topic.
    • The “Process A” topic has the collection type attribute assigned
    Figure 30. Rendered Process Topic.

    The following PDF example shows a sample process of the structure visible in Process Map Structure.

  • When you want to enhance navigation between certain sections in a web format like webhelp

Maintenance Considerations

Keep the following considerations in mind when working with map links:

  • Map links do not limit topic reuse because you link topics on a map level.
  • Map links are based on map structure. If you change the map structure, they links will be updated.

Publishing Considerations

Keep the following considerations in mind when publishing map links:

  • Map links resolve at publish and link text is populated with the topic titles.
  • If you publish to a print-friendly output (for example, PDF), links may reference a page number.
  • You must use the DITA Open Toolkit and set the args.rellinks parameter to all.