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:

  1. Right-clicking in 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:

  1. Open a topic.
  2. Select Tools>Update Cross-References, and the Update Cross-Reference dialog opens, displaying the destination topics of your Cross-References.
  3. 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.

About The Author

Justin Bondoc

About Justin Bondoc

Justin Bondoc, Sales Engineer II, started at MadCap Software as a technical support engineer and turned to the evangelism team to promote the value of MadCap Software’s products and services to the community. In addition to spending his time educating potential and existing customers about all things MadCap Software, Justin likes listening to hip-hop, tackling his next art project, and exploring his creative side.

Last Modified: February 1, 2019

This entry was posted in MadCap Flare, Tips & Tricks. Bookmark the permalink.


  • Ed Marshall Ed Marshall April 24, 2013 at 7:38 AM


    A very important point (cross-references work well in both online and print outputs). that users might often overlook. MadCap might consider reordering the Hyperlink / Cross Reference options / icons or somehow emphasizing the Cross Reference icon/menu option to indicate it’s the recommended option.


  • josh November 12, 2014 at 2:32 PM

    I wonder if there is a way to automate changing all internal hyperlinks to cross references. I inherited a project that only used hyperlinks.

    • Jose Sermeno Jose Sermeno November 17, 2014 at 1:25 PM

      There is using MadCap Analyzer. From the Analyzer documentation:
      “The Cross-Reference Suggestions window pane displays links in a project that you might want to convert to cross-references. This window pane also provides you with the option to convert the selected links to cross-references. For example, if you have regular text hyperlinks (a tags), you might want to convert them, because cross-references change dynamically and are therefore usually preferred over text hyperlinks.”

      For more info see: https://help.madcapsoftware.com/analyzer7/Default.htm#Nav_Links/Cross_References/Viewing_and_Converting_Cross_Reference_Suggestions.htm

      • Morten Müller March 9, 2015 at 5:46 AM

        Thanks for the info about Analyzer’s x-ref conversion option.

        BTW, I love the hidden advert for Stone Ruination IPA in this article’s Standard Method screenshot. That’s an excellent beer …

  • christine March 17, 2015 at 11:31 AM

    Nice article. I am sold on the value of cross-references. I have a few questions about linking to bookmarks. I am able to create a cross-reference link to a bookmark in another file using the Text Editor (example: Link text).

    This works for both the HTML5 help and PDF output, but it renders an error when I generate the output.

    1) Why is this option not available from the UI? (Or is it and i just have not found it?)
    2) Why does it render an error when I generate the output?


  • christine March 17, 2015 at 11:38 AM

    (Note: The example got omitted when I submitted my comment. The example was a MadCap:xref href where the link was to the topic title .htm file followed by hashtagBookmark.)

  • diane March 30, 2015 at 8:33 AM

    I’m having trouble with hyperlinks to websites. I want to link to our corporate website, but Flare crashes when I try to insert a hyperlink > website > select a Target Frame of New Window and click OK. I’m using Flare 10.2.2

    • Jose Sermeno Jose Sermeno March 30, 2015 at 3:16 PM

      Hi Diane,

      Thanks for the comment. I’m not sure as to what the cause of your issue is – but this is something our tech support can definitely assist with. Please submit a support ticket here: https://www.madcapsoftware.com/support/contactoptions.aspx . Our team will follow up directly – as you obviously shouldn’t have any issues linking to a website.

  • DJ Ames April 2, 2015 at 11:22 AM

    Is there a way to make a cross-reference out of selected words in a sentence? For instance, I want to state “To get started, just log in”. Then I want to use the words “log in” as a cross reference to the “Log Into the ABC Tool”. That is, is there any way to NOT have the cross reference always be the title of the topic I’m referencing?

    • Jose Sermeno Jose Sermeno April 2, 2015 at 12:34 PM

      Hi DJ,

      Yes there is! The text of the x-ref is coming from the style class used on the X-ref. By default the x-ref format contains the {paratext} command that pulls the text from of the topic – you can just remove that and put in whatever text you want to display in its place.

      If you’re linking to a topic, and want to have control of the text that is displayed without having to modify a style class, you could possibly use a text hyperlink instead – but you’d lose the ability to dynamically references page #’s, etc that the x-ref provides. More information on Cross References in Flare can be found here: https://help.madcapsoftware.com/flare11/Content/Nav_Links/Cross_References/About_Cross_References.htm

      • Calgary March 7, 2017 at 1:16 PM

        If I create a style class for cross-references that don’t match the title in the topic I’m linking to, is it true that I’ll have to create a style class for each one of these instances? (i.e., a unique style class for each cross-reference that has text in the link that is different from the text in the topic title). It seems like I can’t simply delete the {paratext} tag and leave it blank.

        • Rachel Kim Rachel Kim March 8, 2017 at 8:57 AM

          For cross-references are meant to reference content in another area, like another topic in the project. The content can be a paragraph, list item, essentially any element inserted into a topic. Since you are referencing content, the referenced content is brought back into the link. So for cross-references, we have to reference some kind of content, so that they are unique.

          Cross-references, unlike hyperlinks, include the referenced text you want to pull in to the link, if that text changes, then the link text will change as well. Hyperlinks are static, and do not update.

          In your cross-reference, if you want to link to something other than the topic title, you can when you edit your link. You don’t have to create a style class necessarily. If you have further questions, please call into our support team, so that we can help you specifically, and understand how you would like it to behave. https://www.madcapsoftware.com/support/

  • DJ Ames April 29, 2015 at 8:55 AM

    Thanks, Jose.

  • Tim April 1, 2016 at 3:31 PM

    I think that it would be much more usable if someone does a:
    link text
    if MadCap would use ‘link text’ as the text in the resulting output, versus ‘See ‘Topic title'”; perhaps the default behaviour could be used for instances where you have no link text.

  • Amy Gilbert October 18, 2016 at 8:19 AM

    The comment about the “Ugly, blue, useless, underlined text” is wrong for a couple of reasons. 1) You can style this text any way you want using css, and 2) It may be ugly as is but it is not completely useless as it lets readers know it’s a link. Blue and underlined are common conventions now not just on the web but all kinds of content, including PDFs, which, let’s face it, are the closes many of us get to “print” nowadays. That said, I do agree that cross references are better because they update, but I have some documents with both (I inherited them) and I styled them to look the same.

  • odenzareg com May 4, 2017 at 1:09 PM

    Adding a cross-reference to a definition for the convenience of the audience may create a problem if you don’t continue to repeat it every time you use the word.

Have Something to Say?

Your email address will not be published. Required fields are marked *