Cross-references & hyperlinks
How an IDML document points at the web and at itself — hyperlinks, bookmarks, cross-references, index markers and tables of contents, and where each lives.
A reference in IDML is a pair: a record in the design map and an anchor in a story, joined by id.
In short IDML has five related kinds of reference. Hyperlinks and bookmarks
point somewhere and leave the text alone. Cross-references, index entries and a table
of contents are text that InDesign generates from other places in the document and
saves as ordinary text. The records (Hyperlink, destinations, Bookmark,
CrossReferenceFormat, Topic) sit in designmap.xml, after the last story
reference. The anchors (a linked stretch of text, a text destination, an index marker)
sit inside the stories. TOC styles live in Resources/Styles.xml.
Five kinds of reference
| Kind | What it is | Where the parts live |
|---|---|---|
| Hyperlink | a source (text, or a page item) that jumps to a URL, a page or a text anchor | Hyperlink and the destination in the design map; HyperlinkTextSource in the story |
| Bookmark | a named entry in a PDF's navigation pane, with no source in the text | Bookmark in the design map |
| Cross-reference | a source whose words are built from its target ("see page 12") | CrossReferenceSource in the story; its CrossReferenceFormat and Hyperlink in the design map |
| Index entry | a point in the text that contributes a page to an index topic | PageReference markers in stories; Topic records |
| Table of contents | a story generated from paragraphs in chosen styles | TOCStyle in Styles.xml; the generated story names it in AppliedTOCStyle |
Hyperlinks and bookmarks are covered in hyperlinks and bookmarks; cross-references and the index in cross-references and the index; and the table of contents in table of contents.
Records and anchors
Each reference splits into a record and an anchor. The records are document-level
elements, direct children of Document in the design map. The anchors live where the
text is:
- a text source wraps the characters a reader clicks, inside the story;
- a text destination is an empty marker,
HyperlinkTextDestination, at the spot a link or cross-reference lands on; - an index marker is an empty
PageReferenceat the spot that contributes a page.
The record names its anchor by Self id, so one destination can be reached from many
sources.
Order matters in the design map
InDesign 20.0.1 binds hyperlinks and bookmarks only when the whole navigation block
(destinations, hyperlinks, bookmarks) comes after the last idPkg:Story reference. A
block placed earlier opens without error and binds nothing. The other rules InDesign
applies to these elements are collected in
what InDesign requires to open a file.
Generated text is saved as text
Cross-references, an index and a table of contents are text that InDesign builds from
the rest of the document: a page number, the words of a heading, a list of entries.
IDML stores the result as ordinary Content in the story. A reader that does not
rebuild them sees the text as InDesign last generated it, which is right until the
pages move.
In Paged: hyperlink and cross-reference sources become PDF links, a table of contents is rebuilt from the document, and new hyperlinks can be added by script and saved back in InDesign's spelling.
Supported · verified
Frequently asked questions
What kinds of references does IDML have? Hyperlinks, bookmarks, cross-references, index entries and tables of contents. The first two point somewhere; the last three produce text built from other parts of the document.
Where are hyperlinks stored in an IDML package?
The Hyperlink element and its URL or page destination are in designmap.xml, after
the last idPkg:Story reference. The linked text is wrapped in a HyperlinkTextSource
inside the story.
Why does InDesign ignore my hyperlinks?
Usually because the navigation block sits before the story references, or because the
Hyperlink names its destination with an attribute instead of a typed
<Properties><Destination> child.
Is a cross-reference's text stored in the file?
Yes. The words InDesign generated are saved as ordinary text inside the
CrossReferenceSource, and the same is true of a generated index or table of contents.
Inline vs anchored positioning
What inline, above-line and custom placement of an anchored object do to the object and to the lines around it, as InDesign lays them out.
Hyperlinks & bookmarks
The Hyperlink element, its text source and its URL, page or text destination, and Bookmark — spelled the way InDesign 20.0.1 reads them.