Inline Links
Local Cross-References
Local cross-references directly link to elements in the same topic.
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.
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
- 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
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
- Open a topic and place your cursor where you want to insert a link.
- In the toolbar, click the Insert Link icon.
- In the Link dialog, from the Link To drop-down menu, select An Element in this file (Local link) .
- Click Select Element .
- Select the element that you want to link to by doing the following:
Peer Cross-References
Peer cross-references directly link to other topics or files in the content library.
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.
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:
- Inserting a key reference. See Key References.
- Inserting a relationship table. See Relationship Table Links.
- Reusing elements. See Element Reuse.
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.
Insert Links to Topic Elements
You create a direct inline link to an element in another topic by using the cross-reference.
External Cross-References
External cross-references directly link to external resources like websites or documents hosted on servers external to your content library.
Overview
- “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.
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:
- Link only to reliable external resources.
- To reduce maintenance, if possible, insert a link to the home page of a website (for example, https://dita-ot.org) rather than a deep link (for example, https://www.dita-ot.org/dev/topics/pdf-customization-example.html).
- If possible, link to external resources by using the Hypertext Transfer Protocol Secure (HTTPS) rather than the Hypertext Transfer Protocol (HTTP).
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
Key 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.
- “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.
Insert Key References
Create an indirect, inline link by inserting a key reference to a key name.
Set Element IDs
You can only link to the elements with an unique ID assigned.