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. Today the parser does not surface this wrapper onto the run — the linked region is not marked on the run text — so the run is read exactly as if the wrapper were absent, and the text flows unbroken. Not yet parsedin-story hyperlink sources not surfaced on runs — paged-parse/src/story.rs
• 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 is not wired yet

The whole chain — source anchor, join element, destination — is read into the document model, but nothing here reaches the page:

• Hyperlink regions are not drawn and not made interactive; the link box, highlight, and border attributes are read past. Parsed, not yet renderedpaged-parse/src/designmap.rs:256
• The in-story HyperlinkTextSource wrapper is not surfaced onto the run, so the linked span is not marked. Not yet parsedpaged-parse/src/story.rs
• Bookmarks are not emitted into any navigation structure. Parsed, not yet renderedpaged-parse/src/designmap.rs:267

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.