When navigating the user to the right content, there’s two ways to point them to the right direction: hyperlinks and Cross-References. A hyperlink is a way for you to architect how a user will get from one place to another. Typically they are blue and are underlined, and when a user clicks on it they will be taken to another place, whether it be to another topic, a bookmark in another topic, or to an external website.
On the other hand, a Cross-Reference functions in the same way that when clicked, it will navigate the user to another location. However, one caveat is that it only allows linking within a MadCap Flare project. So why use a Cross-Reference over a hyperlink?
Hyperlinks are great for when you are linking to an external location, such as a website or a location that is outside of your Flare project. However, the issue with hyperlinks arises when you begin to think about how this will affect the user experience when creating a printed version of the output.
Enter the Cross-Reference.
Cross-References have the advantage of dynamically changing based on your output types. For an online output, a Cross-Reference might look and feel just like a normal hyperlink. However, when going to a print based format, the Cross-Reference will update and show you where the linked element is contained on the printed page. Some examples might be “On the next page” or “On page 24”, so Cross-References can be context-sensitive and will let the user know where the referenced content is in context. Also, if the print output is being viewed electronically on a screen, they will still behave like hyperlinks and allow users to click on the item and take them to the content.
Here’s how to use a Cross-Reference in MadCap Flare:
Quick: If you already have your format set up the way you want it, you can use the “Quick Cross-Reference” method, which is faster but does not have as many options. This method lets you quickly select a bookmark that may already exist in the current file, a file in the same folder, or another file currently open.
Standard: You can use the “Standard” method, opening a Cross-Reference dialog box that provides additional options for selecting styles, properties, and link destinations. There are four different ways to insert a Cross-Reference:
- Right-clicking in the editor then going to Insert > Cross-Reference
- Using the insert ribbon: Links Section > Cross-Reference
- Using the local toolbar of the editor:
- Or if you love keyboard shortcuts use CTRL+Shift+R.
One advantage of the Standard method is that you can select the “Bookmark” icon, easily located in the Cross-Reference dialog box. This will allow you to select elements within your topic to Cross-Reference to and a bookmark will automatically be created, as shown in the dialog box below:
Super fast super easy.
One thing to note: if you insert a Cross-Reference into a topic and later make changes that affect the Cross-Reference, you might find that it isn’t pointing to the correct place.
Example: I create a Cross-Reference to a heading and later decide to change the title of the heading. The Cross-Reference won’t automatically update in the editor. However, these will automatically be taken care of at compile time and will display the correct reference title in the generated output.
However, Flare has the ability for you to update Cross-References in a topic so that you can spot-check Cross-References are linking to the appropriate content. You can do this by taking the following steps:
- Open a topic.
- Select Tools>Update Cross-References, and the Update Cross-Reference dialog opens, displaying the destination topics of your Cross-References.
- Click Update > Save.
PS: Already have a bunch of hyperlinks? Maybe you’re importing a bunch of content that already uses hyperlinks? Use the Cross-Reference Suggestions window pane in MadCap Flare for a list of links that you may want to convert to cross-references.
New to MadCap Flare? Start a free 30-day trial, which comes with free inquiries to our Platinum Level technical support. If you have any questions on how to customize your documentation, a technical support team member is ready to assist you.