Allow internal links to use a short format

An administrator can allow the use of a shorthand syntax when internal links are being created in Inspire. By default, this feature is turned off (set to false) and links use the standard DITA format of {filename}#{rootId}/{elementId}. If you turn this feature on, all links to internal content use the shorthand format of #./{elementId}.

Tips and tricks

In DITA, the shorthand reference syntax #./{elementId} is used for linking to specific elements within a topic.

  • The # symbol indicates a fragment identifier, which is a reference to an anchor within the same document or another document.
  • The ./ part is a relative path notation, meaning the link is pointing to an element within the same topic or document rather than pointing to an external file.
  • The Id attribute in DITA serves as an anchor point for references, allowing elements to be linked reliably.

This format ensures that links remain valid even when content is reused or published in different formats.

When a user works with any of the following tasks, links are used:

  • Autorepair

  • Compare

  • Export

  • Import

  • Merge

  • Open in Oxygen

  • Publish

  • Rebuild Relationships

  • Repair relationship

  • Save As

  • Save As Branch

  • Save As Copy

  • Translation

For an example, in the Oxygen editor, a user sees a reference link if they look at the XML code:

  • Standard DITA format for a link: 
    href="Concept1_6f200718-a1bc-40bf-857c-37d80e4e3d68.xml#lb4_hmn_vrb/ref_8f67f5e9-a534-4b80-9afc-9c01dcd80e9b"
  • Shorthand DITA format for a link: 
    href="#./ref_8f67f5e9-a534-4b80-9afc-9c01dcd80e9b"

For more details, read: What XML code is used for a cross-reference link?

To allow internal links to use a short format:

  1. From the Administration menu, select Advanced Settings, and then Features management.
  2. On the Features Management tab:
    1. After UseShortHandReferenceSyntax, note the state. By default the feature is not enabled, and it says false.
    2. After UseShortHandReferenceSyntax, click Update.
  3. The checkbox is highlighted in blue. To change the state, clear or select the checkbox.

    • To enable the feature, type true.
    • To disable the feature, type false.
  4. Click Update.

    Results: When creating a reference link in Inspire, the link uses one of the following forms:

    • If you turn this feature OFF (set to false): links use the standard DITA format of {filename}#{rootId}/{elementId}
    • If you turn this feature ON: links use the shorthand format of #./{elementId}