Cross-References and Links

In your topics, you can add cross-references or links to:

• Other topics

• Elements in the same topic

• Elements in other topics

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

Cross-References to Other Topics

Use the Insert > Link > Cross reference feature to add a cross-reference to the title of another topic.

Note

You can cross-reference other elements inside other topics too (see Cross-References to Other Topics).

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 another topic:

1. Open the "source" topic in the Paligo editor. The "source" topic is the topic that will contain a cross-reference to the "target" topic.

2. Position the cursor where you want to add the cross-reference, and then select Insert > Link > Cross-reference.

   For a cross-reference, you can also use the keyboard shortcut ( Alt R on Windows, Option ⌥ R on Mac).

3. Use the Link Label field to define the text for the cross-reference. You can enter your own text or leave it blank if you want Paligo to use auto-text.

   

   To find out more, see Auto-Text for Cross-References.

4. Browse to the "target" topic and select either the topic or its fork in a publication, depending on your needs:

   • Link to the topic.

     In most cases, this is the preferable way for cross-referencing other topics. But 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, expand it, and select the link to the topic inside the publication.

     

   Paligo adds the cross-reference to the title of the selected topic.

   

5. Select Save.

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.

Cross-References to Elements in the Same Topic

To add a cross-reference to an element that is elsewhere in the same topic:

1. 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).

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

   

3. 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 the title element as the link should be to the section as a whole, not just the title.

   

Cross-References to Elements In Other topics

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:

1. Open the "target" topic in the Paligo editor. The "target" topic is the topic that contains the element that you want to cross-reference.

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

3. Select Save.

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

5. Position the cursor where you want to add the cross-reference, and then select Insert > Link > Cross-reference.

6. Use the Link Label field to define the text for the cross-reference. You can enter your own text or leave it blank if you want Paligo to use auto-text.

   

   To find out more, see Auto-Text for Cross-References.

7. Browse to the "target" topic and select either the topic or its fork in a publication, depending on your needs:

   Select the arrow next to the topic to expand it and reveal its elements.

   

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

9. Select Save.

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.

Cross-References to Websites and Documents

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.

1. Select Insert> Link > External Website to display the New Website Link dialog.

2. 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).

3. 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:show in the Attributes panel. Set the value to "replace".

Auto-Text for Cross-References

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 (PDF and HTML5).

IDs for Cross-References

Cross-references in Paligo use an 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

• section inside another section

• A structure that can have a title, such as a table.

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 an ID for the element before you can link to it.

It's also possible to choose which elements are given automatically generated IDs by Paligo.

Generate an XML ID for an Element

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

To generate a unique xml:id for an element:

1. Edit the topic that contains the element you want to reference. This element is the target of your cross-reference.

2. Select the target element in the topic.

3. In the element structure menu, select the target element, for example, if you want to link to a procedure, select the procedure element.

4. Select Generate ID.

   

   Paligo generates an xml:id for the element. You can see it in the Element attributes panel.

   

5. Select Save.

6. Edit the topic that is going to contain the cross-reference. You should now be able to add a cross-reference to the element.

   To find out more, see Cross-References to Elements in the Same Topic and Cross-References to Elements In Other topics.

Auto-generated IDs for Cross-References

You can control which elements are given auto-generated ids when you save a topic. The settings that you choose will apply to all topics and all users of your Paligo instance.

Note

We recommend that you leave all of the default settings in place for the XML ids 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.

To choose which elements get auto-generated ids:

1. Edit a topic.

2. Select the Editor Settings icon (cog).

   

3. Select the Global settings tab.

4. In the Autogenerate ID box, add the names of elements that you want to have auto-generated ids. Use a space to separate each element name and make sure to add the element names in lower case. Unless you have a very good reason, it is recommended to not remove any of the default elements that are already there.

   

   For example, in the image shown, we have chosen to auto-generate ids for these elements: section, figure, table, example, equation, procedure, bridgehead, sidebar, note, warning, caution, tip, and important.

5. Select Save Settings to confirm your choices.

Embed Google Doc or OneDrive Documents

You can embed a Google Doc or OneDrive document by using a special type of link.

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

     1. Pick the file you want to embed by selecting the check box in the upper-right corner of the file.

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

2. Insert a link element in your topic where you want to embed the document. It needs to be in a para, 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.

3. Add a role attribute. For a Google Doc, set it to gdoc, and for a OneDrive document, set it to onedrive.

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

Turn Images and Other Elements into 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:

1. Select the mediaobject or inlinemediaobject element.

2. Add an xlink:href attribute.

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

Topic Search for Cross-References

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.

1. Position the cursor where you want the cross-reference and then select Insert > Link to display the New Cross Reference dialog. You can then use the External target tab to browse to the topic you want to link to or you can use the Search field.

   

2. Select the arrow button on the search field to display the search filters.

   

3. 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", and automo?i?e would find both "automobile" and "automotive".

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

Links to Local Files from HTML Output

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:

1. Create or edit the topic that is going to contain the link to the PDF file (or other local file).

2. Select Insert> Link > External Website to display the New Website Link dialog.

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

4. In the Link Target field, enter the location and name of the file you are linking to. For example, "mypdfs/my-local-file.pdf".

   You do not have to include a folder name. We have included "mypdfs" here as an example to show that folder names can be included.

   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.

5. In the element attributes for the link, you will see that Paligo has added an xlink:href attribute. It's value is the link target you entered in the previous step, with http:// automatically added as a prefix. Remove the http:// prefix as you want to link to a local file, not a web address.

   

   xlink:href with http:// prefix. This should be removed for links to local files.

   

   xlink:href with http:// prefix removed, so that the link will go to a local file.

6. Save the topic and then publish it.

7. After publishing, add the local files (PDF etc.,) to the location that you defined as the link target.

Edit a Cross-Reference Link

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

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

3. If you want to go to the target topic, just click the icon on the left.

Tip

You can customize the auto-text generated for cross-references and links, see Cross-Reference Styling (PDF and HTML5).

Automatic Links to Related Topics

You can set Paligo to create automatic links to other related topics. The links appear at the bottom of a topic and help readers to find other relevant information. Using automatic links is much easier and quicker to set up and manage than using manually-entered links.

There are two types of automatic links:

• TOC-based automatic links, which, by default, appear below an "In this section" heading. These are links to topics that are "children" of the topic.

• Taxonomy-based automatic links, which give you control over the relationships between topics. By default, these links appear below a "See also" heading.

To learn how to set up both types of automatic links, see the sections below.

TOC-Based Automatic Links (In this Section Links)

In HTML5 outputs, Paligo automatically adds links to related topics at the bottom of certain pages. They are shown below an "In this section" heading and they link to any topics that are "children" of the current topic.

In the following images, the contents sidebar shows that "The Mission Control Center" is the currently displayed page and it has three "child" topics, which are "Command Center", "Guidance System" and "Ground Segment". As the page has "child" topics, Paligo automatically adds an "In this section" to the bottom of the topic, and it contains links to the three child topics.

If you want to stop the "In this section" links from appearing, you can hide them using CSS:

1. Use a CSS editor to create a CSS file, and add the following CSS to it:

   section-toc section-toc-after {
   display:none;
   }

2. Save the CSS file and upload it to your HTML5 Layout.

   1. In Paligo, select Layout and then select the Layout that you want to use for your HTML5 output.

   2. In the Layout Editor, select CSS, JS, logos and other assets.

   3. In the CSS field, upload your CSS file and then select Save.

When you publish your content using the HTML5 Layout, the CSS is included in the output and the "In this section" heading and links will no longer appear. If you want to make them appear, upload a CSS file that does not contain the CSS you added in step 1 and republish.

Taxonomy-Based Related Topic Links (See Also Links)

Taxonomy tags are labels that you can add to any topic. You can use them to categorize your topics and also to get Paligo to create automatic links between topics in HTML5 outputs. The automatic links appear in a "See also" section at the bottom of a topic.

For example, if you have several topics about batteries, you might create a "Battery" taxonomy tag and add it to each of the battery-related topics. Then you can set Paligo to create automatic links between the topics. Each of the topics will have a "See also" section at the bottom with links to the other topics that have the "Battery" tag.

To learn how to create taxonomy-based links, watch the video or refer to the instructions below.

1. In the Content Manager, open the Taxonomy Manager and then open the Taxonomies branch.

2. Select the option button ( ... ) for the Taxonomies branch, and then select Create taxonomy tag.

   

3. Enter a name for your taxonomy tag. This can be any name, and it is going to be the top-level taxonomy tag, also known as the "parent". We recommend that you call this tag "See Also Links" or something similar.

4. Select the option button ( ... ) for the "parent" taxonomy tag you created in steps 2 and 3, and then select Create taxonomy tag.

5. Enter a name for your new taxonomy tag. This tag is a "child" of the "parent" tag in the taxonomy hierarchy, as it has a direct relationship with the "parent" tag but is at a lower level. Give the "child" tag a meaningful name that categorizes the type of content. For example, if you were creating tags for mobile phone documentation, you might have a tag for "Battery".

   

6. Repeat steps 4 and 5 to create as many "child" taxonomy tags as you need. Each "child" taxonomy tag will be used to define a relationship between your topics. For example, imagine you have a "Battery" taxonomy tag and you add it to 5 topics. In your output, each of those 5 topics will have a "See also" section with automatic links to the other 4 topics that have the "Battery" tag.

   You now have a "parent" tag and one or more "child" tags.

7. Select the option button ( ... ) for the "parent" tag and then select Floating Content Panel.

8. Drag your "child" tags from the Floating Content Panel on to the relevant topics in the Content Manager. Do not drag the top level "parent" tag on to a topic as this will stop the "see also" links from working.

   

   Note

   You can find out which topics are associated with a taxonomy by double-clicking on a taxonomy tag. Paligo displays details for that taxonomy tag, including the names of the topics that use it.

9. Select Layout and then choose the Layout that you will use to publish your content.

10. In the Layout Editor, select Classes and attributes.

11. Set Output taxonomies to Enable.

12. In the Relationship taxonomy section, enter the name of the "parent" taxonomy tag. If you want to include several taxonomy tags, separate each taxonomy tag name with a semicolon.

    

    When you publish, Paligo will search in the "parent" taxonomy tag for any "child" tags. It will then find any topics that use these "child" tags and create "see also" links for them automatically. The links that are added will be to other topics that also use the same taxonomy label.

13. Set Output role attribute as class names to Enable.

14. In the TOC and chunking section, make sure that Use section TOC is set to Default, Before or After.

15. Select Save.

16. Publish your content using the layout you edited. Paligo will create the "see also" links automatically and add them to the bottom of the relevant topics.