Troubleshooting Cross-References
If you are experiencing problems with your cross-references, the following sections may help. They cover the most common scenarios where cross-references are not working as expected and explain how to fix the issues.
To find out if you have broken cross-references, use the broken link report. For details, see Broken Links Report.
Cross-reference Links to Wrong Instance of Topic
If your publication reuses the same topic in several places, you may find that cross-reference links incorrectly open the first instance of the topic. This happens if the cross-references are targeting the topic instead of the fork.
To fix the problem, edit the cross-reference so that it targets the appropriate fork in the publication structure. This is the fork for the instance of the topic that you want to link to in the publication.
For example, let's say you have a "Specifications" topic that appears in three sections in your publication. To link to the second instance of the "Specifications" topic, you need to add a cross-reference to the second "Specifications" fork in the publication structure. When a user selects the link, they are taken to the second "Specifications" topic.
For instructions, see Edit a Cross-Reference.
To learn more about cross-references that target the fork, see Topic or Fork.
Cross-reference is Not Working
If you have a cross-reference that is not working, it could be due to:
-
The target topic or fork does not exist in the current publication.
To fix, you can either:
-
Add the target of the cross-reference to the same publication as the topic that contains the cross-reference (see Add Content to a Publication).
-
Create a parent publication with subpublications. The cross-reference source and target must both exist somewhere in the subpublications, for example, the source in one subpublication and the target in another. Publish the parent publication. For information on using subpublications, see Add Content to a Publication.
-
Use an external link to the published URL of the target topic (see Add External Links).
-
-
The target of the cross-reference did not exist in the help center at the time of publishing.
For integrations, such as Zendesk and Salesforce Knowledge, you need to publish the content twice. This is because on first publish, the target of the cross-reference may not yet exist. On second publish, the target does exist and so the cross-reference can resolve correctly.
-
There may be a technical issue. Contact customer support for assistance.
To find out if you have broken cross-references, use the broken link report. For details, see Broken Links Report.
Cross-reference Text is Incorrect
For cross-references, you can either:
-
Enter the text for the cross-reference manually
-
Set Paligo to automatically match the cross-reference text to the target topic title.
If the incorrect text is showing, it is likely because someone has:
-
Changed the title of the topic
-
Changed the manually-entered text for the cross-reference
To fix, edit the cross-reference to meet your requirements (see Edit a Cross-Reference).
If the text is showing as a number or code, it is likely that the cross-reference is broken due to the target topic not being included in the publication. To fix, add the target topic to the publication and check that the cross-reference is targeting the topic or the publication fork for the topic (see Edit a Cross-Reference).
Unwanted External Links (PDF)
Does your content have plain text URLs that appear as unwanted hyperlinks in your PDF outputs? If yes, it is likely because your PDF reader is converting the text into links automatically.
In most cases, there is an option in the application to turn this functionality on or off. For example, in Adobe Acrobat Reader, there is a setting in Preferences to Create links from URLs that you can enable or disable. It is in the General category.
 |
For details on how to disable automatic conversions of URLs into links, please refer to the official documentation for your PDF reader application.