Hyperlinks & bookmarks

A hyperlink joins a source in the story to a destination by id; a bookmark is a destination with a name and no source.

In short The linked words are wrapped in a HyperlinkTextSource inside the story. The place they jump to is a destination: a HyperlinkURLDestination or a HyperlinkPageDestination in the design map, or an inline HyperlinkTextDestination marker in a story. A Hyperlink in the design map joins the two: Source is an attribute, and the destination is a typed <Properties><Destination type="object"> child that names it as Type/Self. InDesign binds these elements only when they come after the last idPkg:Story reference.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<?aid style="50" type="document" readerVersion="6.0" featureSet="257" product="20.0(32)"?>
<Document xmlns:idPkg="http://ns.adobe.com/AdobeInDesign/idml/1.0/packaging" DOMVersion="20.0" Self="d" StoryList="ustory" Name="with-hyperlink.indd" CMYKProfile="Coated FOGRA39 (ISO 12647-2:2004)" RGBProfile="sRGB IEC61966-2.1" SolidColorIntent="UseColorSettings" AfterBlendingIntent="UseColorSettings" DefaultImageIntent="UseColorSettings">
  <idPkg:Graphic src="Resources/Graphic.xml"/>
  <idPkg:Fonts src="Resources/Fonts.xml"/>
  <idPkg:Styles src="Resources/Styles.xml"/>
  <idPkg:Preferences src="Resources/Preferences.xml"/>
  <idPkg:Tags src="XML/Tags.xml"/>
  <idPkg:MasterSpread src="MasterSpreads/MasterSpread_umaster.xml"/>
  <idPkg:Spread src="Spreads/Spread_uspread.xml"/>
  <idPkg:Story src="Stories/Story_ustory.xml"/>
  <idPkg:BackingStory src="XML/BackingStory.xml"/>
  <HyperlinkURLDestination Self="urldest" Name="https://docs.paged.media" DestinationURL="https://docs.paged.media" DestinationUniqueKey="1" Hidden="false"/>
  <Hyperlink Self="link1" Name="docs link" Source="htsource" Visible="false" Highlight="None" Width="Thin" BorderStyle="Solid" Hidden="false" DestinationUniqueKey="1">
    <Properties>
      <BorderColor type="enumeration">Black</BorderColor>
      <Destination type="object">HyperlinkURLDestination/urldest</Destination>
    </Properties>
  </Hyperlink>
</Document>

Hyperlink: the join

Hyperlink is a direct child of Document. It carries the source as an attribute and the destination as a typed property:

• Source names the source's Self (for text, a HyperlinkTextSource id).
• <Properties><Destination type="object">HyperlinkURLDestination/urldest</Destination> names the destination as its element type, a slash, and its Self.
• Visible, Highlight, Width, BorderStyle and the typed BorderColor property describe the link rectangle in exported PDF.

These rules were measured in InDesign 20.0.1:

• A Destination attribute is ignored. The link opens unbound.
• Destination attribute plus DestinationUniqueKey makes the file unopenable.
• DestinationUniqueKey on its own is optional. It neither helps nor hurts binding.

The source: HyperlinkTextSource

A text source wraps the characters that are clickable. InDesign writes it inside the CharacterStyleRange, around the Content it covers, so a link in the middle of a sentence splits the range's content into three parts: the text before, the source, and the text after. Some generated files wrap whole CharacterStyleRanges in the source instead.

A page item can be a source too (HyperlinkPageItemSource), but none of the 305 documents in the census uses one.

Destinations

A hyperlink lands on one of three kinds of destination.

HyperlinkURLDestination opens a web address, DestinationURL. It is a direct child of Document.

HyperlinkPageDestination jumps to a page in the same document: DestinationPage names the page's Self, and ViewSetting / ViewPercentage say how the viewer frames it on arrival. It is also a direct child of Document.

HyperlinkTextDestination marks a spot in the text. InDesign writes it as an empty element at that spot inside the story, with Self, Name and Hidden; it is not a design-map element. A HyperlinkTextDestination in the design map, with a DestinationText attribute, appears in some generated files; InDesign does not bind it. Text destinations are what cross-references and bookmarks usually point at.

Bookmark

A bookmark is an entry in a PDF's navigation pane. It has a Name and a Destination attribute naming a text or page destination, and no source in the text. Bookmarks nest: a Bookmark inside another is its child in the outline. Like hyperlinks, bookmarks bind only after the last story reference.

In Paged: a hyperlink's destination is found from the typed property, the older attribute, or DestinationUniqueKey resolved through the destinations' keys. Text sources become PDF link annotations, to a URL or to a page; the border and highlight are not drawn. Page-item sources are not read. Bookmarks are kept and saved back. Scripts can add a hyperlink to a URL or a page, but not edit or remove one, and saving writes InDesign's spelling, rewriting a file in the older engine spelling.

Supported · verified

Frequently asked questions

How does a Hyperlink name its destination? With a typed property: <Properties><Destination type="object">Type/Self</Destination></Properties>, for example HyperlinkURLDestination/urldest. A Destination attribute is ignored.

Where does a text destination go? Into the story, as an empty HyperlinkTextDestination element at the anchored position. InDesign does not bind a text destination written in the design map.

Is DestinationUniqueKey required? No. On its own it changes nothing; next to a Destination attribute on the same Hyperlink, it makes the file impossible to open.

Where do the hyperlink elements go in the design map? After the last idPkg:Story reference. InDesign ignores destinations, hyperlinks and bookmarks that come before the stories.

What is the difference between a hyperlink and a bookmark? A hyperlink has a source in the text that a reader clicks. A bookmark has none: it is a named entry in the PDF's navigation pane that jumps to a destination.