Skip to main content

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.


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.

    Element attributes panel showing a para element is selected. It has an xml:id attribute.

    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.

    Close up of element structure menu. The procedure element is selected, revealing a drop down menu. The Generate ID option is highlighted.

    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. Select Link and choose Cross-reference.

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

    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.

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

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

    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.
  8. Select the element you want to cross-reference.


    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.


    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.