Cross-References and Links
Links and cross-references are used for different purposes in Paligo:
-
Cross-references are usually a type of link that points inside the publication. This means that the source topic and the target topic are both included in the publication. However, a cross-reference can also reference Paligo content outside the publication (cross-publication links) when supported by outputs like Zendesk or Fluid Topics.
-
Link points outside the publication, like a website or documents stored on the web.
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.
Tip
If you already have a cross-reference and you need to change it, see Edit a Cross-Reference.
By default, external links are opened in a new browser window in HTML / HTML5 output. To change the default value for all external links the layout settings have to be updated. There are four available options:
-
_blank - Will open the link in a new browser window. Default setting
-
_self - Will open the link in the same browser window.
-
_parent - If the link is nested inside other frames, it will open the closest frame (one level up) in the browser window.
-
_top - If the link is nested inside other frames, it will open the initial webpage (the topmost / outermost frame) in the browser window.
![]() |
The following instruction describes how to change the default link behavior for external links to be opened in the same browser window.
-
Select the Layout tab in the top menu.
Paligo displays a list of Layouts. The list is empty if there are no custom Layouts in your Paligo instance.
-
Select the layout to be updated or Create a Layout.
Tip
You can copy the URL of the layout editor and paste it into a new tab in your browser. This can be useful if you frequently switch between your Paligo content and the layout settings.
-
Select Cross-references in the sidebar.
-
Scroll down to Open external website links in new tab or window section.
-
Select _self from the menu.
-
Select Save.
It is possible to override the default link behavior for individual links by adding the attribute xlink:show
. The following values can be selected for this attribute:
-
New - Will open the link in in a new browser window. This is similar to the effect achieved when using _blank in the Layout settings.
-
Replace - Will open the link in the same browser window. This is similar to the effect achieved when using _self in the Layout settings.
-
Embed - This value specifies that instead of linking to the resource, it will be loaded and shown within the document. This is similar to the effect achieved by an HTML Image tag. Only for customizations
-
Other - This value indicates that other markup is present in the link, which means that the target attribute determines its behavior. Only for customizations
-
None - This value specifies that there is no indication for how to refer to the linked resource. Only for customizations
The following instruction describes how to change an individual link to be opened in a new browser window.
-
Select the link in the topic.
-
Add the
xlink:show
in the Element Attributes Panel. -
Select new from the menu.
-
Select Save.
Paligo content is stored in a database and each element can have its own unique ID. Certain types of content, such as paragraphs, images and variables have a special type of ID called xinfo
and this is always generated by Paligo. Other elements can have an optional ID called
xml:id
and these can be generated automatically by Paligo or manually by you.
Cross-references in Paligo use the id to identify the target of the cross-reference. Paligo creates the id automatically for some types of cross-reference, primarily those to components that can have a title. It is added as an xml:id
attribute. But you may need to add an xml:id
attribute manually for cross-references to other types of content. This applies to cross-references between topics and also cross-references to content inside the same topic, for example, to a subsection.
In most cases, we recommend that you cross-reference to a:
-
Section
-
Subsection - a
section
inside anothersection
-
A structure that can have a
title
, such as atable
.
Note
If you want to cross-reference to a different type of content, that is only possible if that content has an xml:id
. So you may need to Manually Generate IDs for Cross-references before you can link to it.
It's also possible to set Paligo to auto-generate xml:ids
, see Auto-Generate IDs for
Cross-References .
You can only add cross-references to elements that have an xml:id
. If the element you want to reference does not have an xml:id, you can generate one manually. Paligo has a feature in the editor that generates a suitable id for you. It's not a good idea to make up your own id
values, as ids should be unique.
Tip
You can set Paligo to auto-generate the xml:ids
, see Auto-Generate IDs for
Cross-References.
To generate a unique xml:id
for an element:
-
Select the topic or component in the Content Manager.
Paligo opens the content in the Editor.
-
Select the target element In Element Structure Menu and choose Generate ID.
For example, if you want to link to a procedure, select the
procedure
element.Paligo generates an
xml:id
for the element in the Element Attributes Panel -
Select Save.
Note
You should now be able to add a cross-reference to the element, see:
When you save a topic, Paligo can give automatically-generated IDs to new elements. This is a useful feature as IDs are needed for cross-references. This will save you the time and effort of having to add the xml:ids
manually.
You can use the editor settings to control which types of element will get auto-generated IDs. The settings that you choose will apply to all topics and all users of your Paligo instance. Typically, we find that auto-generating xml:ids
for the following elements is sufficient
for most users (if needed, you can add more elements to the list):
section figure table example equation procedure bridgehead sidebar note warning caution tip important
Note
A new element is an element that has been added to a topic since the last time the topic was saved. Paligo only creates auto-generated IDs for new elements, any elements that already existed in the topic do not get auto-generated IDs.
To choose which elements get auto-generated ids:
-
Select the topic or component in the Content Manager.
Paligo opens the content in the Editor.
-
Select the cog icon in the Toolbar.
-
Select the Global settings tab in the Editor Settings.
-
Add the names of elements that should get auto-generated
xml:ids
in the Autogenerate ID field.Use a space to separate each element name and make sure to add the element names in lower case.
Note
We recommend not remove any of the default elements and only add to them if needed. In many cases, linking to a
section
element is sufficient to guide the reader to the relevant information.Caution
If you change the default settings for which elements should get an auto-generated id, we recommend you only include the larger block element structures.
Do not include elements such as
para
andtitle
, as that could cause issues with duplicate ids when you reuse text fragments. -
Select Save Settings.
Tip
It is also possible to manually generate xml:ids
via Element Structure Menu, see Manually Generate IDs for Cross-references
![]() |
In a publication, there is a structure that references all of the topics (and sub-publications) that exist in the publication. Each reference to a topic or sub-publication is called a "fork" and has its own fork:id
. This is just for identifying the connection between the publication
and the topic / sub-publication and point out its position. It is not the same as the topic's own xml:id
.
For example, if you have a "Safety" topic that appears three times in the same publication, you can link to the fork for the second instance and the link will go to the second "Safety" topic. If you linked to the topic instead of the fork, the link would always go to the first instance of that topic.
Note
It is possible to add cross-references to elements inside other topics, see Add Cross-References to Elements In Other topics.
To add a cross-reference:
-
Select the topic or component in the Content Manager.
Paligo opens the content in the Editor.
-
Position the cursor at the insertion point.
-
Select the Insert tab in the Toolbar.
-
Select Link and choose Cross-reference.
Tip
Or skip step 3 and 4 and use the keyboard shortcut Alt + R (Windows) or Option ⌥ + R (Mac) to add the cross-reference.
-
Enter a text as Link Label. Leave it blank if you want Paligo to use auto-text, see Auto-Text for Cross-References.
-
Locate the target in the tree structure or use the quick search.
Tip
Make your search more efficient by selecting which resource types to search for.
-
Select whether to make the cross-reference towards the topic or a fork.
-
Select Save.
Note
If you want to change the cross-reference text or apply auto-text, select it to display the cross-reference editor. You can use that to enable or disable auto-text and change the text of the label. For details, see Auto-Text for Cross-References.
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).
Note
If you are adding a link to a step in a procedure, leave the Link Label field empty. Auto-text is needed for referencing the number of a step.
Also note that when you add the cross-reference, it will appear as a code reference. When you publish, this will be replaced by the step number.
-
Use the Internal tab to choose the element you want to link to.
The Internal target tab contains a list of all of the elements inside your topic that currently have an XML ID. Any elements that do not have an ID are not listed.
If the element you want to link to does not have an XML ID, you can generate an ID manually, see IDs for Cross-References).
Note
To link to a subsection heading in a topic, choose the
section
element of the subsection. Do not choose thetitle
element as the link should be to the section as a whole, not just thetitle
. -
Select Save.
You can use Insert > Link > Cross-reference to add a cross-reference to a specific element in another topic. But this is only possible if the element being linked to has an XML ID. If it does not have an XML ID, you will need to edit the target topic and give the element an XML ID.
Tip
We recommend that you use cross-references between topics only where necessary, to avoid dependencies. Cross-references only work if the source topic (that contains the cross-reference) and the target topic are both included in the publication. For this reason, using cross-references between topics can affect the reuse possibilities for your topics.
To add a cross-reference to an element in another topic:
-
Open the "target" topic in the Paligo editor. The "target" topic is the topic that contains the element that you want to cross-reference.
-
Select the element that you want to cross-reference and look in the Element attributes section.
If the element has an
xml:id
value, you can cross-reference it from another topic.If the element does not have an
xml:id
, you need to get Paligo to generate one. Select the element in the Element Structure Menu and then select Generate ID. Paligo will create an xml:id for the element.For more details, see IDs for Cross-References.
-
Select Save.
-
Open the "source" topic in the Paligo editor. The "source" topic is the topic that will contain a cross-reference to the "target" topic element.
-
Select Link and choose Cross-reference.
-
Enter a text as Link Label. Leave it blank if you want Paligo to use auto-text, see Auto-Text for Cross-References.
To find out more, see Auto-Text for Cross-References.
-
Select whether to make the cross-reference towards the topic or a fork.
Select the arrow next to the topic to expand it and reveal its elements.
-
Select the element you want to cross-reference.
Note
Cross-references to
listitem
elements inside bullet lists and ordered lists (numbered lists) may produce unusual results or be excluded from your published output completely. For these, we recommend that you reference a title element instead and explain which step you are referring to.Paligo does support cross-references to steps in procedures, and these will come out as "Step n" in the published output. We recommend that you also add some text with a cross-reference to the title of the target topic, so that your readers have more context. For example, "see Step 4 in Installing the battery", where "Step 4" is a cross-reference to the step and "Installing the battery" is a cross-reference to the target topic's title.
Paligo adds the cross-reference to your topic.
Note
Cross-references to procedure steps do not show as "Step n" in the editor. The link to the target topic and element is converted into "Step n" when you publish.
-
Select Save.
Tip
If you want to change the cross-reference text or apply auto-text, select it to display the cross-reference editor. You can use that to enable or disable auto-text and change the text of the label, see Auto-Text for Cross-References.
You can insert a link to a website or documents hosted on the web by using the URL of the website or document.
The link label is what the reader will see as the link text in the topic. If you want the link text to be the same as the URL, leave the Link Label field empty (blank).
Tip
By default, external links are opened in a new browser tab in HTML and HTML5 output.
If you want external links to be opened in the same tab, add the xlink:show
attribute in the Element Attributes Panel and set the
value to replace
.
-
Select the topic or component in the Content Manager.
Paligo opens the content in the Editor.
-
Position the cursor where the link is to be inserted.
Tip
Alternatively, highlight the text that you want to use as link label.
-
Select the Insert tab in the Toolbar.
-
Select Link and choose External link.
-
Enter a Link label and Link target.
Leave the link label field empty to show the URL.
-
Select Insert.
-
Select Save.
You can add a link to an email address in your content. When the reader selects the link, their default email application will open and a new email is created, with the link email as the address in the To: field.
-
Select the topic or component in the Content Manager.
Paligo opens the content in the Editor.
-
Enter the email address or other text that will act as the email link.
-
Highlight the text.
-
Select the Insert tab in the Toolbar.
-
Select Link and choose Email address.
-
Enter the Email address that will be added to the To: field in a new email.
-
The Label shows the link text you have entered and highlighted in your topic.
If you want to change it, you can edit it in the Label field.
-
Select Insert to add the link.
-
Select Save.
When you are writing your topics in Paligo, you can add links to external files that will be stored locally, rather than stored on the web. For example, you might want to link to a PDF file that you store in a folder that is added to your output files after publishing.
To link to a local file, use the external website link feature and edit the link:
-
Select the topic or component in the Content Manager.
Paligo opens the content in the Editor.
-
Position the cursor where the link is to be inserted.
Tip
Alternatively, highlight the text that you want to use as link label.
-
Select the Insert tab in the Toolbar.
-
Select Link and choose External link.
-
Enter a Link label and Link target.
Leave the link label field empty to show the URL.
Note
If you want to use a relative link, edit your Layout so that the Use a short and flat URL structure for output files option is enabled. This will create an output with a flat structure, where all HTML files are in one folder.
-
Select Insert.
-
Remove the
http://
prefix to link to a local file, not a web address in the Element Attributes Panel.Paligo automatically adds the prefix
http://
to thexlink:href
attribute entered in the previous step.To the left - The initial
xlink:href
with http:// prefix. This should be removed to link to local files. To the right - The prefix removed to link will to a local file. -
Select Save.
-
Publish the topic.
-
After publishing, add the local files (such as PDF) to the location that you defined as the link target.
With cross-references, you can enter your own text (referred to as a label) or, for some elements, you can use Paligo's auto-text feature. The auto-text that Paligo adds varies depending on the type of element you are cross-referencing.
If you cross-reference any of the following elements, the auto-text uses the text from the title
of the element:
-
table
-
equation
-
example
-
procedure
-
figure
If these elements do not have a title
element, enter your own text and do not use the auto-text feature for the cross-reference.
For most other elements, the auto-text will use the title
of the parent section. For example, if you cross-reference a paragraph in a topic, the auto-text will use the title
for the topic.
If you cross-reference a step
in a procedure, auto-text will come out as "Step n", where n is the number. We recommend that you also add a cross-reference to the target topic's title
so that the user has more context about where the step is located.
Note
The text shown in the Paligo editor is not necessarily what you will see in the published output. For example, cross-references to a step in a procedure appear as a link to the target topic in the editor but are converted to "Step n" as part of the publishing process.
To change the text for a cross-reference, select it to display the cross-reference editor. There, you can edit the label in the field and use the Auto checkbox to enable or disable auto-text. You can only edit the label if Auto is disabled.
![]() |
Tip
You can customize the auto-text generated for cross-references and links, see Cross-Reference Styling.
When you have inserted the link, you have a popup toolbar to edit it when the link is selected.
If the checkbox auto is:
-
Checked (default) - The link will automatically get the target topic title as link text.
-
Unchecked - If you want another link text, just uncheck it and type directly in the link.
![]() |
Tip
You can customize the auto-text generated for cross-references and links, see Cross-Reference Styling.
To edit the link target:
-
Select the blue pen to the right to open the Content Manager browser.
It will show the currently selected target.
-
Select another link target from the browser.
Tip
If you want to go to the target topic, just click the icon on the left.
-
Select Save.
You can embed a Google Doc or OneDrive document by using a special type of link. You need to make your document available for embedding.
-
The way to do this varies depending on the type of document:
-
For a Google Doc, select File > Publish to the web in your Google Doc. Next, copy the Link URL.
-
For Google Slides, select File > Publish to the web in your Google Slides. Next, copy the Embed link. You will need to edit this link before you use it in step 4. When editing, remove the frame information. For example, let's say your embed link looks like this:
<iframe src="https://docs.google.com/presentation/d/e/long_string_of_characters/embed?start=false&loop=false&delayms=3000" frameborder="0" width="960" height="569" allowfullscreen="true" mozallowfullscreen="true" webkitallowfullscreen="true"></iframe>
You should remove
<iframe src=
" at the start and everything after /embed, so that the link looks like this:https://docs.google.com/presentation/d/e/long_string_of_characters/embed
-
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.
Note
This feature is only suitable for documents and cannot be used for images.
-
-
-
Insert a
link
element 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
role
attribute. For a Google Doc, set it togdoc
, and for a OneDrive document, set it toonedrive
. -
Add an
xlink:href
attribute 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.
There may be times where you want to edit a regular topic and add information that is stored in a publication topic. For example, you may want to add the copyright year and holder to a topic.
One way to do this is to use a dynamic variable. This is a reference to another element.
-
Edit your regular topic.
Note
The topic needs to be part of at least one publication. When you publish, Paligo will take the information from the publication's topic and insert it into the dynamic variable.
-
Use the keyboard shortcut to add a dynamic variable.
The keyboard shortcut is:
-
Windows: Ctrl + Alt + Shift + I
-
Mac: Control ^ + Option ⌥ + Shift ⇧ + I
Alternatively, you can add a phrase element and give it the role attribute with a value of
dyntextvar
For more details, see Insert a Dynamic Text Variable.
-
-
Enter the reference in the dynamic text variable. For a reference to the publication topic, use this syntax:
${//d:article/d:info/d:<element>/d:<child element>}$
This structure applies for referencing the various info elements in a publication topic.
-
d:article references the article element in the publication topic
-
d:info references the info element inside it
-
d:<element> references an info element, for example, d:pubdate
-
d:<child element> references a child element of the previous element, for example, d:copyright/d:year is a reference to the year element that is a child of the copyright element.
For example:
${//d:article/d:info/d:copyright/d:year}$
You can add text as well, for example, a common use of dynamic variables is to include the copyright information. That could be a dynamic variable with text at the start and then the reference to the copyright year and copyright holder elements.
Copyright © ${//d:article/d:info/d:copyright/d:year}$ ${//d:article/d:info/d:copyright/d:holder}$
Note
The information from the publication topic does not appear when you view a topic in the Paligo editor. It is added when the topic is processed during publishing.
-
-
Select Save.
When you publish the publication, Paligo will find the referenced elements and insert the values from those into the dynamic variables.
When you add a cross-reference, you can use the New Cross Reference dialog to browse to the topic or elements you want to link to. Alternatively, you can use its search feature.
-
Select the topic or component in the Content Manager.
Paligo opens the content in the Editor.
-
Position the cursor where you want the cross-reference.
-
Select the Insert tab in the Toolbar.
-
Select Link and choose Cross-Reference.
-
Browse to the topic you want to link to or use the Search field.
-
Select the arrow button on the search field to display the search filters.
-
Use the checkboxes to filter your search.
-
Document - If you check the box, Paligo will only search in topics, informaltopics, and other "documents". If you clear the box, Paligo will search in "documents" and also folder names, which is useful if you know the name of the folder that contains the content, but not the name of the "document".
-
Content - Check the box to search in the main body content of your topics. Clear it to exclude the content from your search.
-
Title - Check the box to search in the title element of your topics. Clear it to exclude the title elements from your search.
-
Filename - Check the box to search for the topic name or the publication name, rather than its title.
-
Enable autosearch - Check the box to turn on the autosearch feature. When you start typing in the search field, Paligo will automatically find matches as you type. Clear the box to disable this feature.
-
Wildcard search - Check the box to allow wildcard characters such as * in the text that you will enter in the search field. Wildcard characters can represent any other character. Clear the box if you want Paligo to match by specific characters only.
Use an asterisk (*) to represent one or many characters, or use a question mark to represent any single character. You can use these symbols anywhere in the search string.
For example,
automati*
would find both "automation" and "automatic", andautomo?i?e
would find both "automobile" and "automotive".
-
-
Enter the text you want to search for in the Search field.
Paligo will find the nearest matching results and you can choose which one you want to link to.
-
Select Save.
If an element is reused several times in a publication and you want to link to the element in a specific topic to provide context to the reader, you have to manually create a fork link
for your PDF output.
You can add cross-references to Elements (images, paras, procedures, tables) reused in components or topics, but it will point to where the element was initially created, see Cross-References and Links.
When a topic or component is included in a publication, it gets a unique fork:id
for that specific instance in the publication. By adding the element xml:id
to the fork:id
, you get a fork link
that leads to the element in the reused position. The fork link will by default show the page number within square brackets for PDF output. To style the cross-reference, see Cross-Reference Styling.
![]() |
Note
A manually created fork link
only works in the publication it originates from.
To manually create a fork link:
-
Generate an
xml:id
for the target element, see Manually Generate IDs for Cross-references. -
Open the topic that will have the cross-reference.
-
Select Link and choose Cross-reference in the toolbar.
-
Enter a Link label. (Optional).
-
Navigate to the publication.
Note
The cross reference dialog shows the targets both as part of the publication and as topic (outside the publication tree). It is important to select the one in the publication tree to get the
fork link
!Learn the difference between topics and forks, see Topic or Fork.
-
Select the arrow in front of the topic to see linkable elements.
-
Select the element to make it appear as a link in the topic. It will lead directly to the element origin.
-
Copy the element
xml:id
(from the front slash "/" and forward) from the created link. -
Redirect the cross-reference to point to the topic containing the reused component.
In our example it is "Battery disposal".
Note
The cross reference dialog shows the targets both as part of the publication and as topic (outside the publication tree). It is important to select the one in the publication tree to get the
fork link
!Learn the difference between topics and forks, see Topic or Fork.
-
Paste the element
xml:id
after the topicfork:id
in the Element Attributes Panel.In our example, the Battery disposal
fork:id
is "urn:resource:fork:37742".This
fork link
will now show the table in the reused position. -
Select Save.
-
Publish the topic as PDF to test the link.
The preview is not able to visualize
fork links
.
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
mediaobject
orinlinemediaobject
element. -
Add an
xlink:href
attribute. -
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.
By adding the role
attribute to an external link and setting the value to external
, the webpage appears as an iframe
element in your output as below.
Note
Paligo cannot validate external links, therefore it is necessary for you to test and verify that it works.
To embed an external link:
-
Select the topic or component in the Content Manager.
Paligo opens the content in the Editor.
-
Position the cursor inside a para.
-
Select the Insert tab in the Toolbar.
-
Select Link and choose External link.
-
Enter a Link label and Link target.
Leave the link label field empty to show the URL.
-
Select Insert.
-
Select the
link
element in the Element Structure Menu and choose Go to element. -
Add the
role
attribute in the Element Attributes Panel and set the value toexternal
. -
Add the
xlink:href
attribute and enter the URL as value. -
Select Save.
-
Select the Preview tab in the Toolbar.
-
Publish to HTML5 to test that the embedded page works.