Skip to main content

Add a Cross-Reference to an Element in Another Topic

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 topic that contains the element that you want to link to.

  2. Position the cursor in the element that you want to link to.

  3. Select the element in the Element Structure Menu and choose Go to element.

    Step element is selected in the element structure menu. A menu is revealed and Go to element is selected.

  4. Check if an xml:id is added in the Element Attributes Panel:

    • If an xml:id is already added, skip the next step.

    • If there is no xml:id, you will need to add it, continue with the next step.

    Element attributes for a step. The step has an xml:id attribute and value.
    Element attributes section shows that the step element is selected.

  5. Select the element in the Element Structure Menu and choose Generate ID.

    Paligo will generate an xml:id attribute for the list item or step automatically.

    Step is selected in the element structure menu, revealing a menu. The Generate ID option is selected.

  6. Select Save. Save icon.

  7. Open the topic that is going to contain the cross-reference.

  8. Position the cursor where the link is to be inserted.

    Tip

    Alternatively, highlight the text that you want to use as link label.

  9. Select the Insert tab in the Toolbar.

    Insert tab on the main editor.

  10. Select Link and choose Cross-reference. Insert_Link.png

    Cross-reference_LinkMenu_small.png

    Tip

    Or use the keyboard shortcut Alt + R (Windows) or Option ⌥ + R (Mac) to add the cross-reference.

  11. Enter a text as Link Label. Leave it blank if you want the link text to be the same as the topic title, see Auto-Text for Cross-References.

    New cross-reference dialog has a Link Label field and a Link Target section. The Link Target section contains a hierarchy of folders, publications, and topics.

  12. Choose to cross-reference directly to the topic or to a fork in the publication:

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

    Link target section of new cross-reference dialog. A callout highlights an arrow next to a topic. The topic is expanded to reveal its elements.

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

    Example of a cross-reference to a step in a procedure, after being added to a 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.

  14. Select Save. Save icon.

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.