Getting Started

Adding Cross-References and Links

You can cross-reference other topics, elements in topics, and web sites/documents/email addresses.

  1. Select Insert> Link.

  2. Select the type of link. For a cross-reference, you can also use the keyboard shortcut ( Alt R on Windows, Option ⌥ R on Mac).

  3. For a cross-reference, you have the option to link to a topic ("External" tab), or to an element within the same topic ("Internal" tab).

    1. Use the External tab to browse to the topic that you want to link to.


      For linking to other topics, you have two options:

      • Linking to the actual topic (the "origin topic") in the Content Manager, i.e not its reference inside a publication. This is in most cases the preferred option if you are not reusing the same target topic multiple times in the same publication, as the link will refer to the origin topic and not a specific instance of it. No matter what the context the topic is reused in, the links will resolve.

      • Linking to the topic reference inside a publication. This is the preferred way if you are reusing the target topic multiple times in the same publication, as it will then allow you to point to a specific one of those instances.


      You do not have to put anything in the Link field unless you want a different text than the title. The link will automatically use the title of the target topic (which is usually what you want). And it will be updated automatically if you change that title later.

    2. Use the Internal tab to choose the element you want to link to. The elements shown are all in the topic you are currently editing.


      If you want to link to a subsection heading in a topic, choose the section element of the subsection. Do not choose the title element as the link should be to the section as a whole, not just the title.

  4. For links to external web sites or documents, enter the url.


    By default, external links to other web sites open in a new browser tab in HTML/HTML5 output. Should you in some case want it to open in the same tab, just add an attribute called xlink:show in the Attributes panel. Set the value to "replace".

  5. When you have inserted the link, you have a popup toolbar to edit it when the link is selected:


    If auto is checked (default), the link will automatically get the target topics's title as link text. If you want another link text, just uncheck it and type directly in the link.

  6. To edit the target of the link, just click the blue pen icon to the right. This opens a Content Manager browser widget that shows you the currently selected target, and you can select another one.

  7. If you want to go to the target topic, just click the icon on the left.


You can customize the text generated for cross-references and links. See Cross-reference text options (PDF and HTML5).

Turning images and other elements into links

You can also make images work as links. There is however no selection dialog to insert that type of link. You do it by adding the link target as an attribute on the image itself:

  1. Select the mediaobject or inlinemediaobject element.

  2. Add an xlink:href attribute.

  3. Add the target value using the following syntax:


    The first part is always the same, and the last part (the numbers) is the id of the target topic.


    You can get the id of the target topic by opening the Structure View for that topic, where you find it at the top of the metadata.

    Another way to get the entire link value is to simply make a regular ("dummy") cross-reference, and then copy the value from there and then delete the dummy cross-reference.

Cross-references to elements inside other topics

In general with single-sourcing content, it is recommended to avoid making too many cross-references if you don't really have to, as you create dependencies. And when you do cross-reference, it's preferable to try to make them to entire topics.

However, when you do have the need to cross-reference another topic on a more granular level, i.e to an internal element inside another topic, it's no problem:

  1. In your "source topic" (the one with the link), create a regular cross-reference to a topic.

    This will create an attribute for the link called xlink:href with a value that points to the topic, looking something like this: urn:resource:component:31214.

  2. Now get the id of the internal element in the other (target) topic, e.g a figure or a procedure step. If it doesn't have an id (xml:id) you can add it and give it a value.


    The value should be a unique id. You can set which elements automatically get unique ids generated in the Editor Settings.

    You can also easily add auto-generated ids for any element by using the command in the Element Structure Menu.

  3. In the source topic where you want to link to this element in the other topic, now add a slash ("/") and then the element id you just got at the end of the xlink:href attribute value. I.e it could look something like this:



Currently a cross-reference to an element inside another topic does not show the content of that element, like an internal link in the same topic does. But it will do so when you publish.

Using links to embed Google Doc or OneDrive documents

It's possible to embed a Google Doc or OneDrive document by using a special type of link.

  1. If the document you want to embed is not already available to embed, you need to do either of the following depending on the type of document:

    • For Google Doc, do this under File > Publish to the web inside your Google Doc.

    • For OneDrive:

      1. Pick the file you want to embed by selecting the check box in the upper-right corner of the file.

      2. Select Embed at the top of the page, and then choose Generate.

  2. Insert a link element in your topic where you want to embed the document. It needs to be in a para, but the para should only contain that link.


    You can add link text to make it easier to see what it links to, but that text will not be used in the output.

  3. Add a role attribute. For a Google Doc, set it to gdoc, and for a OneDrive document, set it to onedrive.

  4. Add an xlink:href attribute and set the value to the embed URL.


  • The document will not be embedded in the topic inside the editor, it will only show that there is one embedded. The embedding itself happens when you publish.

  • Embedding is only available for HTML5 or Zendesk output. For other formats a regular link will be created.