Cross-References and Links
In your topics, you can add cross-references or links to:
-
Web sites or documents that are stored on the web
-
Files that are stored locally, such as PDFs (for HTML outputs)
-
Email addresses.
You can also use images as links, and use links to embed GoogleDoc and OneDrive documents.
We recommend that you only use cross-references where necessary. This is because with cross-references, you create dependencies. If one topic links to another, both of those topics need to be included in a publication, otherwise the link will not work. As a result, the topics are dependent on each other and this makes it more difficult to reuse them independently.
If you already have a cross-reference and you need to change it, see Edit a Cross-Reference Link.
If you want to add a cross-reference from one topic to another topic:
-
Select Insert> Link > Cross-reference to display the New Cross-Reference dialog.
For a cross-reference, you can also use the keyboard shortcut ( Alt R on Windows, Option ⌥ R on Mac).
-
In the Link Label field, enter the text that you want to be shown for the link. This is what the reader will see as the text for the link in the topic. You only need to enter a label if you want the link text to be different to the title of the topic.
If you want the link text to be the same as the topic title, leave the Link Label field empty (blank).
-
Use the External target tab to browse to the topic that you want to link to.
For linking to other topics, you can:
-
Link to the topic. In most cases, this is the preferable way for linking to other topics. However, if you are going to reuse the same target topic multiple times in the same publication, you will need to link to the "fork" reference instead.
To add a topic reference, select the topic. Topics have black icons.
-
Link to the "fork" reference to a topic. The "fork" reference is inside a publication, and it is the reference between the publication and a single use of the topic. You should use "fork" links if you are reusing the target topic multiple times in the same publication.
When you link to the "fork", you link to a specific instance of the topic. For example, let's say you reuse a "Safety" topic in chapters 1, 5, and 8 of your user guide. You can get a topic to link to the "Safety" topic in chapter 5 by linking to the "fork" reference in chapter 5 instead of the actual "Safety" topic.
To add a "fork" reference, find the publication in the External target tab, expand it, and select the link to the topic inside the publication.
-
If you want to add a cross-reference to an element that is elsewhere in the same topic:
-
Select Insert> Link > Cross-reference to display the New Cross-Reference dialog.
For a cross-reference, you can also use the keyboard shortcut ( Alt R on Windows, Option ⌥ R on Mac).
-
In the Link Label field, enter the text that you want to be shown for the link. This is what the reader will see as the text for the link in the topic. You only need to enter a label if you want the link text to be different to the title of the topic.
If you want the link text to be the same as the topic title, leave the Link Label field empty (blank).
-
Use the Internal tab to choose the element you want to link to. The elements shown are all in the topic you are currently editing.
Note
If you want to link to a subsection heading in a topic, choose the
sectionelement of the subsection. Do not choose thetitleelement as the link should be to the section as a whole, not just thetitle.
You can add cross-references to elements that are in other topics, such as procedures and nested sections (subsections). However, we recommend that you only do this where necessary, to avoid dependencies.
-
In your "source" topic (the one that will contain the link to another topic), add a link to the other topic. At this stage, you only need to link to the other topic's title. So you now have a "source" topic that contains a link to the "target" topic.
-
Open the "target" topic in the Paligo editor. In the content, select the element that you want to link to. You should see the element in the element structure menu. For example, if you want to link to a procedure, select any part of the procedure in the main text, and then select the
procedureelement in the element structure menu.
Note
To add a link to a structure's
title, such as thetitleof a table, make sure you select the element that represents the entire structure. For example, to link to thetitleof an example, select theexampleelement and not thetitleelement. -
Select Go to element.
-
In the Element attributes section, find and copy the
xml:idvalue.
Note
If the element does not have an
xml:idattribute, add one by selecting the element in the element structure menu, and then select Generate ID.
-
Open the "source" topic and select the link that you added in step 1.
In the Element attributes section, the xlink:href attribute for the link is shown. It has a value that is a reference to a topic, and the reference looks something like this:
urn:resource:component:2649.
-
Add a forward slash / to the end of the xlink:href and then paste in the xml:id value from your "target" topic.
To get the cross-reference to work, you have to include the element prefix with the xml:id. This is the name of the "target" element followed by a dash. For example, for procedures, the prefix is
procedure-, for sections it issection-, for bridgeheads it isbridgehead-and so on.You should now have an
xlink:hrefwith a value that looks something like this:urn:resource:component:2649/procedure-idm45858214294032Where the first part of the value is a reference to a topic's ID and the second part is a reference to a type of element and the id of that element.
Note
The Paligo editor does not show the content of cross-references to elements in other topics. However, the content is included when you publish.
You can add cross-references to websites and documents that are hosted on the web. These cross-references use the address (URL) of the website/document.
-
Select Insert> Link > External Website to display the New Website Link dialog.
-
In the Link Label field, enter the text that you want to be shown for the link. This is what the reader will see as the text for the link in the topic. You only need to enter a label if you want the link text to be different to the URL of the website or document.
If you want the link text to be the same as the URL, leave the Link Label field empty (blank).
-
In the Link Target field, enter the URL for the link.
Tip
By default, external links to other web sites open in a new browser tab in HTML/HTML5 output. If you want an external link to open in the same tab, add an attribute called
xlink:showin the Attributes panel. Set the value to "replace".
You can embed a Google Doc or OneDrive document by using a special type of link.
-
If the document you want to embed is not already available to embed, you need to do either of the following depending on the type of document:
-
For Google Doc, do this under File > Publish to the web inside your Google Doc.
-
For OneDrive:
-
Pick the file you want to embed by selecting the check box in the upper-right corner of the file.
-
Select Embed at the top of the page, and then choose Generate.
-
-
-
Insert a
linkelement in your topic where you want to embed the document. It needs to be in apara, but the para should only contain that link.Tip
You can add link text to make it easier to see what it links to, but that text will not be used in the output.
-
Add a
roleattribute. For a Google Doc, set it togdoc, and for a OneDrive document, set it toonedrive. -
Add an
xlink:hrefattribute and set the value to the embed URL.
Note
-
The document will not be embedded in the topic inside the editor, it will only show that there is one embedded. The embedding itself happens when you publish.
-
Embedding is only available for HTML5 or Zendesk output. For other formats a regular link will be created.
You can also make images work as links. There is however no selection dialog to insert that type of link. You do it by adding the link target as an attribute on the image itself:
-
Select the
mediaobjectorinlinemediaobjectelement. -
Add an
xlink:hrefattribute. -
Add the target value using the following syntax:
urn:resource:component:31214.The first part is always the same, and the last part (the numbers) is the id of the target topic.
Tip
You can get the id of the target topic by opening the Structure View for that topic, where you find it at the top of the metadata.
Another way to get the entire link value is to simply make a regular ("dummy") cross-reference, and then copy the value from there and then delete the dummy cross-reference.
-
When you have inserted the link, you have a popup toolbar to edit it when the link is selected:
If auto is checked (default), the link will automatically get the target topics's title as link text. If you want another link text, just uncheck it and type directly in the link.
-
To edit the target of the link, just click the blue pen icon to the right. This opens a Content Manager browser widget that shows you the currently selected target, and you can select another one.
-
If you want to go to the target topic, just click the icon on the left.
Tip
You can customize the text generated for cross-references and links. See Cross-Reference Styling (PDF and HTML5).