Inserting Cross-References

A cross-reference is an automated link that is based on a format with commands. This method of linking saves time because you don't have to type the link text each time, or manage it over time if the destination content changes. Cross-references are recommended when you are linking from one place in your project to another (as opposed to linking to external files or websites). The format can be controlled in your stylesheet. This lets you keep links consistent and change them in just one place by using the MadCap|xref style (or a class of it that you have created). Cross-references are also useful for converting online links to page number references when you are producing printed output (by having a separate format for the cross-reference style in the print medium of the stylesheet).

For more information see Cross-References.

How to Insert a Cross-Reference—Standard Method

  1. Open the content file.
  2. In the XML Editor place your cursor where you want to insert the cross-reference.
  3. Do one of the following, depending on the part of the user interface you are using:

    • Ribbon Select the Insert > Cross-Reference.
    • Keyboard Shortcut Press CTRL+SHIFT+R.
    • Local Toolbar In the local toolbar of the XML Editor, click .
    • Right-Click Right-click in the editor and select Insert > Cross-Reference. This context menu option is available only when your cursor is located in certain places in the editor (e.g., not in a drop-down effect).

    The Insert Cross-Reference dialog opens.

  4. From the Link to drop-down field, select a way to identify the topic or bookmark to which you want to link. Based on the option you choose, the section below gives you a list of selections or additional fields to complete.

    Topic in Project 

    This option lets you search for a topic within your project. After you select this option, use the area below to navigate to the file that you want to link to and select it. By using the buttons in the local toolbar, you can view all files in a list, view files in their folder structure, and use other options.

    Option

    Description

    Shows all of the files in the project in a list below. Click the button again to switch to a folder tree view. You can click the File, Type, or Path column headers to sort the list alphabetically by that column data.

    Click to show or hide folders where files are kept.

    Shows or hides the folders that the files are stored in.

    Click to show or hide files within a folder.

    Shows or hides the files. If you click this button when the Show Folders button Click to show or hide folders where files are kept. is selected, the area splits into two. The folder is shown on the left side, and the files and subfolders within it are shown on the right.

    Click to move up one folder level.

    If the Show Files button Click to show or hide files within a folder. is the only one selected, you can click this button to move up one folder level.

    Lets you filter the kinds of files shown below. Depending on the task you are performing, this field may already be populated with the most appropriate file type(s).

    You can also click to display and select any bookmark or a location using a particular style (including classes and IDs). If necessary, a bookmark will be created at that location if one does not exist. If you want to clear a bookmark in the link, select it and click the button at the bottom of the dialog.

    Place in This Document

    This option displays any bookmarks, headings, and other elements in the current file. Expand the appropriate section and select the element to which you want to link. If you select anything other than an existing bookmark, Flare will insert a new bookmark at that destination in the file.

  5. In the Cross-Reference Properties section, select the MadCap|xref style that you want to use for the cross-reference.

    Initially, you may see only the parent MadCap|xref style in the list. In the XRef Format area to the right, you can see the current format associated with that tag. Initially this format is as follows for the different mediums:

    • Default Medium {paratext}
    • Print Medium "{paratext}" {pageref}

    The command {paratext} means that the text of the paragraphed bookmark—or the text of the first paragraph found in the topic—will be displayed at that spot. The {pageref} command in the print medium format allows for context-sensitivity (see Creating Context-Sensitive Cross-References).

    You can: (1) use the parent MadCap|xref style with its current format, (2) use the parent MadCap|xref style and change the format to something else, (3) create a new class of the MadCap|xref style and provide a custom format for it, or (4) use a class that you have already created previously.

    It is a good idea to create classes because you may eventually want to use multiple kinds of cross-references in your project. Each class that you create can be used to display cross-references in a different format. For more information see Creating Selectors and Styles and Stylesheets.

  6. If you want to use the parent MadCap|xref style with its current format, or a class that you have created previously, click MadCap:xref or the name of the class, respectively. Then continue with Step 13.
  7. If you want to use the parent MadCap|xref style but change the format, click MadCap:xref and then Edit. The Edit Cross-Reference Style Class dialog opens. Continue with Step 10.
  8. If you want to create a new class of the parent MadCap|xref style, click New. The New Cross-Reference Style Class dialog opens.
  9. In the XRef Class field, give your new class a name.
  10. In the Stylesheet to modify field, select the appropriate stylesheet (if different from the one shown). If you are using a primary stylesheet (recommended), only that stylesheet is shown in this field. If you are not using a primary stylesheet, the stylesheet that you select needs to be applied to the topic in which you are inserting the cross-reference. See Associating Primary Stylesheets With All Files and Associating Stylesheets Locally With Specific Files.
  11. In the Enter format field, provide the format for the style. This format can be a combination of text that you type and automated commands that you select. You can select commands from the list by double-clicking them. They are then added to the "Enter format" field.

    Command

    Description

    b

    Start bold text

    /b

    End bold text

    bg

    Start new background color

    /bg

    End background color

    color

    Start new text color

    /color

    End text color

    default

    Reset all font changes

    ext

    File extension

    family

    Start new font family

    /family

    End font family

    file

    File name, including extension

    filename

    File name, without extension

    h1

    Text of first heading 1 paragraph

    h2

    Text of first heading 2 paragraph

    h3

    Text of first heading 3 paragraph

    h4

    Text of first heading 4 paragraph

    h5

    Text of first heading 5 paragraph

    h6

    Text of first heading 6 paragraph

    i

    Start italic text

    /i

    End italic text

    page

    Page number

    pagecount

    Page count

    pageref

    Context-sensitive page reference

    paranum

    The autonumber text of bookmarked paragraph.

    paranumonly

    The autonumber only of bookmarked paragraph

    paratext

    Text of bookmarked paragraph

    paraxml

    Text and markup of bookmarked paragraph

    path

    File path

    size

    Start new font size

    /size

    End font size

    sub

    Start subscript text

    /sub

    End subscript text

    sup

    Start superscript text

    /sup

    End superscript text

    title

    Title of document

    u

    Start underlined text

    /u

    End underlined text

    url

    File path, URL syntax

    [variable]

    Available variables can be entered in the cross-reference format.

    Example If you want the cross-reference to include text (such as "For more information see"), simply type it in this field. You can also double-click any of the commands to add them to this field. For example, you might want to add the text of the first paragraph in the destination file to the cross-reference format. The command for this is {paratext}. Descriptions for each command are displayed in the list.

    Some commands include a start tag and an end tag. For example, if you want a portion of the cross-reference to be displayed in bold, you would place your cursor in the "Enter format" field where want to start the bold font and double-click b in the list below. Then place your cursor where you want the bold font to end and double-click /b from the list.

    So in the end, your cross-reference format might include a combination of text and multiple commands, such as:

    For more information see {b}{paratext}{/b}

    A format such as this one might display a link in the output like this:

    For more information see My Destination Topic

    For additional information and examples, see Cross-References.

    Note For print-based and EPUB output you can create context-sensitive cross-references, which automatically change the text in the link based on the relationship of the cross-reference and the target location. See Creating Context-Sensitive Cross-References.

  12. Click OK.
  13. (Optional) In the Target Frame field of the Insert Cross-Reference dialog, click the drop-down arrow to select the way the linked destination will open. This option can be used to open the destination topic or file in a popup.

    • Page Default The destination file opens in the same window as the output window.
    • Parent Frame The destination file opens in the parent frame of the current topic while hiding that topic.
    • New Window The destination file opens in a new browser window.
    • Same Frame The destination file opens in the same window frame as the current topic.
    • Top Frame The destination file opens in the same output window, removing all other framesets. You might use this option, for example, if the destination topic has its own frameset.
    • Popup Window The destination file opens in a popup box on top of the current topic.
  14. (Optional) In the Screen Tip field, you can type a phrase that will appear when the end user hovers over the cross-reference in the output. When you enter a screen tip, it is added as a <title> tag in the markup.

    For more information see Accessibility.

  15. (Optional) In the Alternate Text field, type a phrase that describes what the element is about. This option should be used to increase accessibility for users who are unable to view an element. See Alt Text and Title Attributes.
  16. Click OK. The cross-reference is added to the topic. You can change the appearance of the link (e.g., color, underline) by modifying the style (e.g., MadCap|xref or MadCap|xref.MyStyle) in the Stylesheet Editor.
  17. Click Save the active file. to save your work.

How to Insert a Cross-Reference—Drag-and-drop Method

  1. Open the content file.
  2. Open the Content Explorer, File List window pane, or TOC Editor. If necessary, float and position the window pane or editor (see Customizing the Workspace) so you can see both it and the XML Editor at the same time.

  3. From the Content Explorer, File List window pane, or TOC Editor, click and drag the topic you want to link. The cross-reference is added to the topic.

  4. Click Save the active file. to save your work.

If the animation below is cut off, you can see the complete animation by clicking the link under it to open the full topic.

Note You can change the default drag-and-drop behavior to insert a hyperlink rather than a cross-reference. See Setting the Default Paste Behavior.

How to Insert a Cross-Reference—Quick Cross-Reference Method

  1. Open the content file.
  2. In the XML Editor right-click at the location where you want to insert the cross-reference.
  3. From the context menu select Insert > Quick Cross-Reference.
  4. Select the appropriate submenu, depending on the option that helps you find the destination the fastest.

    • Bookmarks Lets you select any bookmarks that you have already inserted into the current file.
    • Same Folder Lets you select any files that are contained in the same folder in the Content Explorer.
    • Open Documents Lets you select any other files that are also currently open in the workspace.

  5. From the next submenu choose the bookmark or file. The cross-reference is added to the topic. You can change the appearance of the link (e.g., color, underline) by modifying the style (e.g., MadCap|xref or MadCap|xref.MyStyle) in the Stylesheet Editor.
  6. Click Save the active file. to save your work.

What’s Noteworthy?

Warning It is recommended that you avoid creating links to snippets. This is primarily due to the nature of snippets, which are designed to be inserted into multiple files. Let's say you have a heading style in a snippet and that snippet is then inserted into 12 different topics. In another topic, you might decide to create a cross-reference that points to the heading in that snippet. But which of those 12 topics is it supposed to point to in the output? There is no way for Flare to know this, so you could end up with some very undesirable results. For this reason, it's a good idea not to link to any content in a snippet.

Note The default format for the primary cross-reference style (MadCap|xref) is already set up to create context-sensitive cross-references. If you have been using the old default cross-reference formats and want to continue using them, you can edit the MadCap|xref style and replace the new formats with the older ones. The old cross-reference format for the default style medium is See "{paratext}". The old format for the print medium is See "{paratext}" on page {page}. See Editing Cross-Reference Style Formats.

If you have already edited the MadCap|xref style in a stylesheet before upgrading to a new version, your custom format will not be affected. You will only see a change if you have never changed the default format from older versions.