Hyperlinks & bookmarks

A hyperlink is a source/destination pair joined by id, and a bookmark is a source-less navigation anchor — both kept by the parser, neither drawn on the page yet.

In short In IDML a hyperlink is two elements, not one: a source — the stretch of text or the frame a reader interacts with — and a destination — the URL, page, or text anchor it jumps to. The Hyperlink element in the design map joins them by id, so a single destination can be reached from many sources. A bookmark is the source-less cousin: a named anchor that appears in a PDF's navigation outline with no clickable region in the body. Paged's parser keeps the fields it needs to follow each link or bookmark, while the renderer does not yet draw link regions, make them interactive, or emit a navigation structure.

A hyperlink is a pair: a source — the stretch of text or the frame the reader interacts with — and a destination — the place it jumps to. IDML splits the two into separate elements and joins them by id, so the same destination can be reached from many sources. The Hyperlink element in the design map is the join: it names a Source and points at a Destination. The source's anchor lives back in the story; the destination is its own element, also in the design map.

The package below carries one complete hyperlink — a HyperlinkURLDestination, a HyperlinkTextSource, and the Hyperlink that ties them together — plus the in-story anchor that the source records. The renderer reports one page, one story, one run: the three Content chunks (the text before the link, the linked words, and the text after) collapse into a single run, and the hyperlink metadata rides alongside without changing the count.

<?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"/>
  <HyperlinkTextSource Self="htsource" Name="docs-link-source" AppliedCharacterStyle="CharacterStyle/$ID/[No character style]" Hidden="false"/>
  <Hyperlink Self="link1" Name="docs link" Source="htsource" Visible="true" Highlight="None" Width="Thin" BorderStyle="Solid" Hidden="false" DestinationUniqueKey="1" Destination="urldest"/>
</Document>

Hyperlink

The join element, listed flat in the design map. The parser keeps the four fields it needs to follow the link — the id, the human name, the source ref, and the destination — and reads the appearance attributes past. Note that the destination is read from DestinationUniqueKey when present (the integer key a destination element exposes) and otherwise from Destination.

The source side

A Hyperlink's Source names one of two anchor kinds. Both are recorded at document level; the text kind also leaves a wrapper inside the story.

• A HyperlinkTextSource wraps a stretch of text inside a CharacterStyleRange. In the example, it surrounds the words "paged media docs" between two plain Content chunks. The parser now records the enclosing source span's id on each run it covers, so the linked region is known and the renderer can place a PDF link annotation over exactly those glyphs. Supportedin-story hyperlink/cross-reference source spans are recorded on the runs they cover and emitted as link annotations
• A HyperlinkPageItemSource makes a whole page item (a frame) the source via its SourcePageItem attribute, with no in-text wrapper.

The destination side

A hyperlink jumps to exactly one of three destination elements, each listed in the design map. They share Self, Name, and a DestinationUniqueKey integer key; what differs is the kind of place they name.

A third kind, HyperlinkExternalPageDestination, names a page in another document via a DocumentPath and a DestinationPageIndex (1–9999); it shares the page destination's view-setting vocabulary.

Bookmark

A bookmark is the source-less cousin: a named anchor that appears in a PDF's navigation outline and jumps to a destination, with no clickable region in the body text. The parser keeps its id, name, and destination ref.

What reaches the page, and what does not

The whole chain — source anchor, join element, destination — is read into the document model and the navigation half of it now reaches a PDF export:

• Hyperlink and cross-reference source spans emit PDF link annotations (URL and go-to-page); the in-story source wrapper is recorded on the runs it covers. Supportedlink annotations emitted over source spans
• Bookmarks emit PDF navigation destinations (the outline entries). Supportedbookmarks become PDF go-to destinations
• What is still not drawn is the on-page visual decoration — the link box, highlight, and border attributes are read past, because an underline or tint on the live page is an editor affordance rather than a faithful-render output. Parsed, not renderedlink box / highlight / border appearance read past; no on-page decoration

Frequently asked questions

How does IDML store a hyperlink? As a pair of elements joined by id. The Hyperlink element in the design map names a Source and points at a Destination; the source's anchor lives back in the story, while the destination is its own element (a URL, page, or external-page destination) also listed in the design map. Splitting source from destination lets the same destination be reached from many sources.

What is the difference between a hyperlink and a bookmark? A hyperlink has a source — a span of text or a whole frame the reader interacts with — that jumps to a destination. A bookmark has no visible source: it is a named anchor that shows up in a PDF's navigation outline and jumps to a destination, with no clickable region in the body text. The parser keeps a bookmark's id, name, and destination ref.

What hyperlink destinations does the parser read? A hyperlink jumps to one of three destination elements: a HyperlinkURLDestination (a web address), a HyperlinkPageDestination (a page in this document), or a HyperlinkExternalPageDestination (a page in another document via a DocumentPath and DestinationPageIndex). The parser reads each destination's id, name, key, and target; the appearance and view-setting attributes are read past.

Does Paged make hyperlinks clickable? No. The whole chain — source anchor, join element, and destination — is read into the document model, but the renderer does not draw the link region, make it interactive, surface the in-story HyperlinkTextSource wrapper onto the run, or emit bookmarks into a navigation structure. These features are parsed, not rendered for this phase.