Inserting Cross References into Topics

Inserting Cross-References into Topics

Cross-references let you create "automated" links that are based on commands you provide. This allows you to keep links consistent and change them in just one place by using the <MadCap:xref> style. Cross-references can also be used to convert online links to "page number" references when you are producing printed output. For more information, see About Cross-References.

How to insert a cross-reference into a topic

Open a topic.

In the XML Editor, place your cursor where you want to insert the cross-reference.

Select Insert>Cross-Reference. The Insert Cross-Reference dialog opens.

In the Link to area, select a way to identify the topic or bookmark to which you want to link. Based on the option you choose, the section to the right gives you a list of selections or additional fields to complete.

Place in this document This option displays any headings and bookmarks in the current topic. After you click this option, use the section to the right to choose the topic or bookmark to which you want to link.
Open document This option displays all other topics that are currently open in your project. After you click this option, use the section to the right to choose the topic file to which you want to link. You can also click the Bookmark button to display and select any bookmarks within the destination topic.
File in current folder This option displays all other topics that are located in the same folder in the Content Explorer. You might have topics in various folders if you have previously organized your topics. After you click this option, use the section to the right to choose the topic file to which you want to link. You can also click the Bookmark button to display and select any bookmarks within the destination topic.
Recent file This option displays the most recent topics that have been opened in your project. After you click this option, use the section to the right to choose the topic file to which you want to link. You can also click the Bookmark button to display and select any bookmarks within the destination topic.
Topic in Project This option lets you search for a topic within your project. After you select this option, click the Topic button. In the Open File dialog, navigate to the file that you want to link to, select it, and click Open. You can also click the Bookmark button to display and select any bookmarks within the destination topic.

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

Initially, you will see only the parent <MadCap:xref> tag in the list. In the XRef Format area to the right, you can see the current format associated with that tag. By default, it initially is: See "{paratext}". 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.

You can: (1) use the parent <MadCap:xref> tag with its current format, (2) use the parent <MadCap:xref> tag and change the format to something else, (3) create a new class of the <MadCap:xref> tag 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 New Style Classes and About Styles and Style Sheets.

If you want to use the parent <MadCap:xref> tag 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.

If you want to use the parent <MadCap:xref> tag but change the format, click MadCap:xref and then Edit. The Edit Cross-Reference Style Class dialog opens. Continue with Step 10.

If you want to create a new class of the parent <MadCap:xref> tag, click New. The New Cross-Reference Style Class dialog opens.

In the XRef Class field, give your new class a name.

In the Stylesheet to modify field, select the appropriate style sheet (if different from the one shown). If you are using a master style sheet (recommended), only that style sheet is shown in this field. If you are not using a master style sheet, the style sheet that you select needs to be applied to the topic in which you are inserting the cross-reference. See Applying Master Style Sheets and Applying Style Sheets to Topics.

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.

To see the available commands and their descriptions, click here.

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 auto-number text of bookmarked paragraph.
paranumonly	The auto-number 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

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 About Cross-References.

Note: For print-based 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.

Click OK.

(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 will open in the same window as the output window.
Parent Frame The destination file will open in the parent frame of the current topic while hiding that topic.
New Window The destination file will open in a new browser window.
Same Frame The destination file will open in the same window frame as the current topic.
Top Frame The destination file will open 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 will open in a popup box on top of the current topic.

(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.

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.

Press CTRL+S or click

to save your work.