ClickHelp User Manual

Ways to Handle Broken Links

Broken links are unacceptable in documentation because they influence the quality of documentation and SEO. When using ClickHelp, you can handle broken links easily. The ClickHelp engine checks:

  • Cross-topics links inside topic content.
  • Resource links in style files.
  • Links in scripts files.

First of all, let's make it clear how broken links can appear:

  • Broken links can appear in projects after importing.
  • You added the wrong link when editing a topic.
  • You changed URLs or renamed/deleted files.
  • A web link became invalid (page removed).

Depending on the type of broken link, you can use different methods to find and fix those. In this topic, we'll learn how to do this:

Using Link Viewer to Check Topic Links

If you need to check links in a specific topic, do the following:

  • Open a necessary topic and go to Properties. To learn how to open topic properties, refer to this topic: Topic Properties.
  • Then click Link Viewer.
    Link Viewer section in the topic's properties
  • On the Link Viewer page, you'll see a list of broken links, as well as the lists of inbound and outbound topic links.
    The Link Viewer page

Checking For Broken Links in a Project

If you need to check for broken links for a whole project, do the following:

  • Publish your project using the Private visibility.
    Choose the private visibility in the Publishing wizard
  • On the 3rd step of the publishing process, you'll see a list of broken links. You can use the Download Log as PDF command to have this log in the PDF format to act on those broken links later.
    Broken links displayed on the third step of the Publishing process

Fixing Broken Image Links

Let's suppose there is a broken image reference in some imported content. Let's see how to fix this:

  • The image will not be shown in your topic, but it's still there, you can find its code in the Source view:
    The markup of the image in the HTML mode
  • In order to fix the link in all topics where it is used, copy the image URL from the Source editor and use Global Find ad Replace with the File Link search mode:
    Use the File Link search mode in the GF&R dialog
  • To learn more, refer to this topic: Finding Content with Regular Expressions and Other Techniques.

Updating Variable and Snippet References

A snippet or a variable used in a topic can also be considered a link since they point to some other entity. Before you rename a variable or change a snippet topic URL, you may want to find where it is referenced from. To do this, you can follow the steps below:

  • In the topic editor, click on a variable.
  • Then click the Global Find and Replace icon.
    The Global Find and Replace icon
  • The Global Find and Replace window will open.
  • Click Find All.
    The Find All button in the GF&R dialog
  • You'll see the result.
    The results of the GF&R operation

Fixing Broken Content Links

Imagine, you found a broken link in your content that returns 404, to handle it, do the following:

  • Click the link.
    The Link in the text
  • A new tab will open.
  • Copy that broken link from the browser address bar.
    Copy the broken link from the address bar
  • Go to Global Find and Replace.
  • Paste the link to the search string.
  • You'll see all the occurrences of the broken link.
  • Choose a topic(s) where you want to replace the broken link with the right one.
  • Fill in the 'replace with' field.
  • Click Replace Selected or Replace All depending on your goal. 
  • Then, you'll see the log.