When referencing a piece of content within your documentation, there are two ways to point users in 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. It is a link (much like in a web browser) that takes you to a particular destination. Typically they are blue and underlined, and when clicked, it directs users either to an internal or external location such as another article, topic, or website.
On the other hand, a Cross-Reference functions in a similar way that when clicked, it will navigate the reader to another location. However, a Cross-Reference is recommended when you want to link your reader to other locations in your project, like another topic, or to a section in a topic. 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 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.
This is where the Cross-reference really shines.
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:
1. Right-clicking on the editor then going to Insert > Cross-Reference
2. Using the insert ribbon: Links Section > Cross-Reference
3. Using the local toolbar of the editor:
4. 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.
Maintaining Cross-References
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.
Editor's Note: Originally published on January 19, 2017.
