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.

   	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.
   	Shows or hides the folders that the files are stored in.
   	Shows or hides the files. If you click this button when the Show Folders button 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.
   	If the Show Files button 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.

    Clear filter

    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 to save your work.

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 to save your work.

What’s Noteworthy?