Link to existing content

Linking FAQ's

What's the difference between a cross-reference and linking to a file?

Both options create a link that references content inside of Inspire.

A cross-reference link lets you link to a DITA topic and select a location within that topic, such as:

• a different location within the current component
• a different component
• a specific location in another component

If you need to link to a file that isn't a DITA topic, such as an image, you can link to a file. The component's title is used to create the link.

What's the difference between a content reference and a cross-reference?

A content reference - this inserts a read-only copy of the element you've chosen from the component you dragged into the topic.

A cross reference - this inserts a link to the element you've chosen from the component you dragged into the topic. Readers will have to click the link and open another topic to see the referenced content.

What XML code is used for a cross-reference link?

If you create a reference to content in a separate file, the file name is included:

<filename>#<rootId>/<elementId>

If you create a reference to content that exists in the same file, DITA assumes it's the same, so the file name is dropped:

#<rootId>/<elementId> 

Can I cross-reference anything in a topic?

You can only create a cross-reference to elements with ID values. An administrator can configure elements in the Element Management module and set Yes or No for the Needs Id property.

• If you need to reference an element that doesn't have an ID, contact your administrator.
• To configure elements, an administrator can follow the steps in Manage elements.

How is the link text created?

Depending on the element that you cross-reference, the text of the link varies in the following ways:

• A concept displays the concept's title
• A figure displays the figure title
• A table displays the table's title
• A title element displays the href value
• An item in a numbered list (ol) displays the step number
• An item in a bullet list (ul) displays the number the item is from its parent (For example, if you reference the second bullet, the title of the cross-reference link displays the number 2.)
• A row displays the href value
• All other elements display the href value

How do I know my link is up-to-date?

To refresh links and references to ensure the most recent information is being displayed, in the Oxygen editor, go to the toolbar and click Refresh references.

Are ditabase files supported?

Yes. Inspire now supports content references to ditabase topics. A ditabase topic is a composite topic. Before maps, ditabase was used to collect multiple topics and structure them within a single topic file.

• If you're editing a topic that has a conref to a ditabase topic, the link is resolved in Oxygen without errors.
• When you click Save and Submit, Inspire creates a valid reference.

Can I copy a link between components?

Yes.

When you're working on a document in the Oxygen-based editor, you can reuse content from other components by creating a cross-reference. After creating a cross-reference, you can copy it and paste the link into a different component.

• Make sure you select both the link icon and entire link text when copying.

For more help, read Copy a cross reference between components.

Can I create a link using conref keys?

Yes.

Keys are useful because the link is connected to the content in one place in the map, which makes it easier to update than a conref that uses a file name to find the content. You need the following files to add a link using a key:

• A reusable topic
• A DITA map that lists the reusable topic
• A component that uses the reusable content

Follow the steps in: Insert a key reference as a link.

If you want to actually insert the content using a key so the reader doesn't have to navigate away from the topic, follow the steps in: Insert content using a conkeyref.

Why am I asked to submit my changes again?

An administrator can turn on an optional feature to help you manage referenced content. You only see a confirmation in the Oxygen editor after you click Save and Submit if:

• Your administrator has enabled the SubmitConfirmation option.
• You are making changes to content that is referenced by another component.

In the Oxygen editor, if both of the above conditions are true, after you click Save and Submit, you see the following screen:

You can see the component that will be affected by your updates on the Where used screen.

You can choose from the following options

• Submit. Saves the changes you made which will also appear in the other components that reference the content.
• Save as... Opens the Save As screen to create a new component with the changes you made. This option closes the original component without saving any changes. The newly created component opens in Oxygen. This option does not update any of the other components that referenced the original component you were editing.
• Branch. Opens the Save As Branch screen that lets you specify where to save it (target folder) and a branch label. This options saves the current content as a new branched component. This option does not update any of the other components that referenced the original component you were editing.
• Cancel. Closes the Where used screen and returns you to the Oxygen editor. No changes are saved to the database.

In the Oxygen editor, if any of the following are true, you won't see a confirmation.

• Your administrator has NOT enabled the SubmitConfirmation option.
• Your administrator has enabled the SubmitConfirmation option, but you are making changes to content that is NOT referenced by another component.

In these cases, Inspire saves your changes and closes the Oxygen editor without any other interaction.