# Hyperlinks and bookmarks Hyperlinks, their text sources, page and URL destinations, and bookmarks. Implemented in `src/model/hyperlink.rs`. | Class | Object | IDML element | |---|---|---| | 0x13501 | Hyperlink | `Hyperlink` (designmap) | | 0x13502 | Text source | `HyperlinkTextSource` or `CrossReferenceSource` (story text) | | 0x13503 | Page item source | `HyperlinkPageItemSource` (designmap) | | 0x13504 | Text or paragraph destination | `HyperlinkTextDestination`, `ParagraphDestination` (story text) | | 0x13505 | Page destination | `HyperlinkPageDestination` (designmap) | | 0x13506 | URL destination | `HyperlinkURLDestination` (designmap) | | 0x13552 | External page destination | `HyperlinkExternalPageDestination` (designmap) | | 0x1354C | Bookmark | `Bookmark` (designmap) | ## Evidence The first facts below came from five corpus pairs. They were checked again on the later corpus: 108 of its 654 same-version pairs have hyperlinks (75 trustworthy), with 11,166 `Hyperlink`, 10,491 `HyperlinkTextSource`, 191 `CrossReferenceSource`, 430 `HyperlinkPageItemSource`, 1,159 `HyperlinkPageDestination`, 27,724 `HyperlinkURLDestination`, 643 `HyperlinkExternalPageDestination`, 1,021 `HyperlinkTextDestination`, 169 `ParagraphDestination` and 1,074 `Bookmark` elements. Hyperlinks, sources, external page destinations and bookmarks have `Self` equal to the INDD UID; the other destinations are found by `DestinationUniqueKey`. Counts below without a qualifier are over all 108 pairs. ## Hyperlink (chunk 0x13502) | Offset | Contents | IDML | |---|---|---| | 0 | u32 text source UID (0 for none) | `Source` | | 4 | u16 0 | | | 6 | u16 hidden (1 true) | `Hidden` | | 8 | u32 key | `DestinationUniqueKey` | | 12 | u32 destination kind (below) | | | 16 | u32: 2007 in 11,121 of 11,164; 2006 (37), 2005 (4) or 2019 (2) in the others | | | 20 | u32 0x13501 | | | 24 | flag byte and string | `Name` | | | flag byte and string (empty) | | `Source`, `Hidden`, the key and `Name` match in all. 48 hyperlinks in one pair have source UID 0; IDML writes them without `Source`, which the schema requires, so the converter leaves them out. | Kind at 12 | IDML `Destination` | |---|---| | 2000 | `n` (no destination), or a list (another document) | | 2001 | `HyperlinkPageDestination/…` (1,151) | | 2002, 2017, 2018 | `HyperlinkURLDestination/…` (9,030) | | 2003 | `ParagraphDestination/…` (191, cross-references) | | 2004 | an external page destination's UID (576) | **Destination.** IDML writes it as `Properties/Destination`. A hyperlink whose object has chunk 0x1359F (u32 0x13501, u32 1, u32 link UID) points into another document: IDML writes a list destination (file name, volume name and three numbers) for 155 of 156 such hyperlinks. The volume and the numbers are not located, so the converter leaves `Destination` out for them (the schema allows that). For all other hyperlinks the destination is the destination object with the same key (10,946 of 10,947; each key names one object), or, with kind 2000 and no such object, the value `n` (61). In the trustworthy pairs, after this rule, the converter's `Destination` is right for 2,850 of 2,878 hyperlinks it writes and left out for the other 28 (list destinations). **Appearance (chunk 0x13553, 18 bytes).** Over all 11,164 hyperlinks the chunk is `00 00 01 00 00 00 b6 00 00 00 b10 00 00 00 00 00 00 00`. Byte 6 takes the values 0x1A, 0x1B, 0x1D, 0x20, 0x21 and does not follow any IDML attribute. Byte 10 is `Highlight`: 0 `None` (11,156), 1 `Invert` (8). `Visible="false"`, `Width="Thin"` and `BorderStyle="Solid"` are the same in all 11,164, so their fields cannot be located; the converter writes them for hyperlinks whose chunk has this pattern. `BorderColor` is `Black` for all 10,588 hyperlinks of kinds other than 2004; the 576 of kind 2004 (two pairs) have `Black` (255), `Violet` (280) or `Green` (41), and no chunk of the hyperlink object differs between the colours, so the converter writes `Black` only for the other kinds. The attribute order is `Self Name Source Visible Highlight Width BorderStyle Hidden DestinationUniqueKey`, then `Properties` with `BorderColor` and `Destination`. ## Text source (class 0x13502) **Chunk 0x13504:** u8 hidden (1 true), u8, u32 hyperlink UID, flag byte and string (`Name`), u32. `Name` and `Hidden` match in 43 of 43. **Chunk 0x1352E:** u32 range strand (below), u32 node index in its tree, u32 character style UID. A style UID of 0 is written as `AppliedCharacterStyle="n"` (39 of 39); other values are the style (4 of 4, `CharacterStyle/$ID/Hyperlink`). **Chunk 0x135B7: alternative destination.** u32 type (2 = `TocTextAnchor`, the only type seen), flag byte and string (`TextAnchorName`), u32 (`IndexMarkerId`), u32 length *n* and *n* UTF-16 code units of text segments (`TocEntryPageNumberString`), u32 (`TocEntryLevel`). IDML writes it as `Properties/AlternativeDestination` with the attributes `Type IndexMarkerId TextAnchorName TocEntryPageNumberString TocEntryLevel`. 1,163 of 1,163 sources with the chunk match on all five attributes, and the chunk ends after the last field. In the page number string, a character below U+0020 is written as the text `` with the code in lowercase hexadecimal (U+0008, before the page number, in all samples). In the trustworthy pairs the converter writes 1,048 of 1,048 of them right. **Chunk 0x135A0: cross-reference source.** All 191 class 0x13502 objects with this chunk are `CrossReferenceSource` elements; the 10,489 without it are `HyperlinkTextSource`. Layout: u32 1, flag byte and string (the page-number text, such as `21`, or empty), flag byte and string (empty in every sample), u32 cross-reference format UID (`AppliedFormat`, the `CrossReferenceFormat` `Self`; 191 of 191), then six u32 not identified. `Name`, `Hidden` (chunk 0x13504) and `AppliedCharacterStyle` (chunk 0x1352E, `n` in all 191) are read as for text sources (191 of 191). The attribute order is `Self AppliedFormat Name Hidden AppliedCharacterStyle`. Their hyperlinks point at `ParagraphDestination`s (kind 2003). The schema allows no `Content` in `CrossReferenceSource`, but InDesign writes `Content` directly in 66 of them; the other 125 hold a `TextVariableInstance` (92) or `CharacterStyleRange` elements (33). The converter writes a cross-reference source that holds only a text variable instance inside the character range, as InDesign does, and any other one at paragraph level, around a `CharacterStyleRange`, so that the output stays valid. That differs from the reference structure in 66 sources (15 in one trustworthy pair), whose inner ranges count as extra values. ### Position in the text IDML writes the source as a `HyperlinkTextSource` element around its text inside a `CharacterStyleRange`. The INDD stores the text ranges of a story's sources in a tree: - One of the story's strands (chunk 0x223, `objects.md`) is of class 0xCA1C. Its chunk 0x16126 starts with the UID of the tree's first page. - A page is an object of class 0x1610A. Chunk 0x16127: u32 next page, u32 previous page, u32 strand, u32, u32 *n*, *n* u32 node indexes, u32 node count, then the nodes. Each node is u32 class (0xCA1E), u32 size (60), and the node data. - Node data: u16, u32, u32, u16, then four references, each u32 object (the strand, or 0 for none) and u32 node index: parent, the node itself, left child, right child. Then u32 value, u32 length, u32 text source UID, u32 0. - The root's value is its start in the story text (UTF-16 offset). A left child starts *value* before its parent, a right child *value* after it. - In the endnote story the same tree also holds the endnote ranges (class 0x2804, `footnotes.md`). Checked by taking the INDD story text at the computed start and length and comparing it with the text in the IDML source element: 43 of 43 (in 4 the text contains U+0008, which IDML writes as a processing instruction). In the 251 little-endian files there are 59,532 nodes in 90 files; all are class 0xCA1E and name a class 0x13502 object. ### Placement The story text at a source's start and length equals the text of the IDML source element for 10,642 of 10,680 text and cross-reference sources over all pairs (1,823 of 1,846 paragraph-level ones in trustworthy pairs); the 38 others hold tracked changes or a footnote reference, whose text IDML writes inside the source. No two ranges overlap, none is empty, and 525 end where the next begins. IDML places the source element at the lowest level that holds its whole extent (all pairs): | Extent | Parent | Children | Sources | |---|---|---|---:| | Within one character style range | `CharacterStyleRange` | `Content`, `Br`, … | 6,546 | | Several character style ranges of one paragraph style range | `ParagraphStyleRange` | `CharacterStyleRange` | 3,714 | | Several paragraph style ranges | `Story` | `ParagraphStyleRange` | 5 | Another 154 are inside `Change` and 72 inside `XMLElement`. A range that continues past the source boundary is split there: the `CharacterStyleRange` before a paragraph-level source has the attributes of the first range inside it in 3,689 of 3,714 (1,551 of them empty, because the source starts where the range starts), and the range after it continues with the same attributes when the source ends inside a range (562). InDesign keeps the empty range, which holds no text. In 3 sources whose last character is a paragraph's return, InDesign also writes the next paragraph's empty `ParagraphStyleRange` inside the source. The converter writes: - a source within one character style range inside it, as before; - a source over several character style ranges of one paragraph style range as a child of the `ParagraphStyleRange`: the ranges at its ends are split at the source's start and end, and the parts inside are written as `CharacterStyleRange` children of the source. The empty ranges InDesign keeps are not written, as they hold no text; - a source that spans paragraph style ranges, or that is not inside one list of text runs (the story's or one table cell's), is left out with a warning. The schema allows `HyperlinkTextSource` in `CharacterStyleRange` and `ParagraphStyleRange`, not in `Story` or `Cell`, so the 5 story-level sources (all in one pair) cannot be written validly. **Sources at inserted text.** Where a tracked change run with an insertion entry (`objects.md`, tracked changes) starts at a source's first character and ends before the source does, IDML writes an empty ``, with the run's attributes, before the source, and writes the source's first character without a `Change`. For a paragraph-level source the empty `Change` is the last child of a `CharacterStyleRange` of its own, with the attributes of the source's first range, after the text deleted there (`Change DeletedText`); for a character-level source it is in the open range, after the deleted text. A source that ends inside the run or with it is inside the run's `Change` instead (sources in tracked changes, below). Trustworthy pairs: IDML has 1,681 empty `Change` elements in 19 documents, each directly before a source (1,668 paragraph-level, 13 character-level), and the rule gives the same sources in every pair (stale pairs: 385 of 385). **Sources in tracked changes.** A character-level source whose whole extent lies inside an inserted-text change run is inside that run's `Change`: `CharacterStyleRange > Change > HyperlinkTextSource`, the `Change` closing after the source (or going on as the range's `Change` when the run continues). A change that starts inside a character-level source and ends with it is inside the source. A paragraph-level source inside a change written above the character ranges is inside that `Change` (`objects.md`, tracked changes). The converter does not wrap a source whose text holds a table, an anchored item or an XML marker, which a `Change` cannot hold. Over the trustworthy pairs of the corpus after 2026-10 this removes all 220 extra values of `HyperlinkTextSource/Change` (44 sources in 10 documents), where the converter had written the `Change` inside the source; no value is lost. A paragraph-level source that holds an XML marker is left out with a warning; a character-level source ends at an XML marker. A character-level source that holds an anchored object is left out (below); at paragraph level the anchored object is inside an inner `CharacterStyleRange`, which the schema allows. Every text source that the converter left out as "spans several text ranges" in a trustworthy pair before paragraph-level sources were written (3,986) is, in the IDML, paragraph-level outside footnotes (2,012, 167 of them in table cells), story-level (5), inside a tracked change (1,723) or in a footnote (246). After this rule the converter writes 2,026 paragraph-level sources in the trustworthy pairs, with their 2,052 hyperlinks, all matching the reference. ## Page item source (class 0x13503) **Chunk 0x13505:** u8 hidden (1 true), u8, u32 hyperlink UID, flag byte and string (`Name`), u32. **Chunk 0x13525:** u32 page item UID (`SourcePageItem`). The page item's chunk 0x1351D names the source back. IDML writes `HyperlinkPageItemSource` in `designmap.xml` with `Self`, `Name`, `SourcePageItem`, `Hidden`, in that order, after the destinations and before the hyperlinks. 430 of 430 match on `Hidden` and `SourcePageItem` (rectangles and groups, classes 0x6201 and 0x401), and the converter writes 136 of 136 in the trustworthy pairs with all values right. A source whose page item is not written is left out, with its hyperlink. ## Page destination (class 0x13505) **Chunk 0x13507:** u8 hidden, u8, flag byte and string (`Name`), u32 key (`DestinationUniqueKey`). **Chunk 0x13527:** u32 page UID (`DestinationPage`), f64 zoom as a fraction, u32 view setting, then four f64. Over 41 destinations (39, plus 2 in a pair from another save): - `Name`, `DestinationUniqueKey` and `Hidden` (all true): 41 of 41. - `DestinationPage`: 39 of 39, and 0 of 2 in the other save. - Zoom 1 and `ViewPercentage="100"`: 39 of 39; the other two have 91 in IDML, also with zoom 1. The converter writes the zoom × 100. Over the 654 pairs of the later corpus: 1,157 of 1,159 destinations (33 files), with values from 75.35 to 800. - View setting 1 and `ViewSetting="FitWindow"`: 41 of 41, and 592 of 592 in 26 files of the later corpus. View setting 0 and `ViewSetting="Fixed"`: 567 of 567 in 11 files. The converter writes these two and leaves the attribute out for other codes. - One file without an IDML has three destinations with view setting 0 and zoom 0. The schema allows `ViewPercentage` from 5 to 4000, so the converter leaves it out (with a warning) for a zoom outside 0.05–40. - After the view setting, chunk 0x13527 has four f64: `ViewBounds` `Left`, `Top`, `Right` and `Bottom`, in that order (1,157 of 1,159 in the later corpus). 590 have 1e+256 in all four, which IDML writes as `1e+256`. IDML writes them as `Properties/ViewBounds` with the attributes `Top Left Bottom Right`. - `NameManually="true"` is in all 1,159 page destinations of the later corpus. The flag byte before the name is 0 (4) or 2 (1,155), so it does not hold this value; no field was located. The converter writes `true`, the corpus value, after `Name`. `Self` is `HyperlinkPageDestination/` and the name. ## Text and paragraph destinations (class 0x13504) **Chunk 0x13508:** u8 hidden (1 true), u8, flag byte and string (`Name`), u32 key (`DestinationUniqueKey`). **Chunk 0x13526:** u32 owner UID (class 0x1353C), u16 kind: 0 `HyperlinkTextDestination` (1,021 of 1,021), 1 `ParagraphDestination` (169 of 169). The owner object is an owned item (run kind 0x209, `objects.md`) of the story strand at the destination's position, and that position holds U+FEFF (1,190 of 1,190). The owner's chunk 0x1352B starts with the destination UID (1,021 of 1,021 text destinations checked). IDML writes the destination as an empty element at that position, in place of the U+FEFF, inside the `CharacterStyleRange` (746 text destinations and all 169 paragraph destinations; the other 275 are inside tracked changes). `Self` is `HyperlinkTextDestination/` or `ParagraphDestination/` and the name, escaped as for page destinations. Attributes: `Self`, `Name`, `Hidden`, `DestinationUniqueKey`, in that order. Names need not be unique: one pair has 7 text destinations with the same name, and IDML writes 7 elements with the same `Self`. The converter writes them so: in the trustworthy pairs 685 of 685 text and 119 of 119 paragraph destinations are reproduced with all values, and 48 stories whose text differed only by the U+FEFF became identical. Hyperlinks find them by key and bookmarks by UID, like the other destinations; a destination that is not written in a story (inside text the converter leaves out) is not referred to. ## URL destination (class 0x13506) **Chunk 0x13509:** u8 hidden, u8, flag byte and string (`Name`), u32 key. **Chunk 0x100B:** flag byte and string, the URL (`DestinationURL`). The 4 URL destinations in the pairs match on `Name`, `DestinationURL`, `Hidden` (false) and `DestinationUniqueKey`, but their name and URL are the same text, so they do not show which chunk is which. In a pair from another save, an INDD destination has an e-mail address followed by ` 1` in chunk 0x13509 and a `mailto:` URL for that address in chunk 0x100B, and the IDML has a destination named with the address alone and with that `mailto:` URL as `DestinationURL`. Chunk 0x100B is therefore taken as the URL. `Self` is `HyperlinkURLDestination/` and the name with `:` written as `%3a`. ## External page destination (class 0x13552) | Chunk | Contents | IDML | |---|---|---| | 0x13580 | u8 hidden, u8 0, flag byte 1, string (empty in all), u32 key | `Hidden`, `DestinationUniqueKey` | | 0x1B8 | u32 page index from 0 | `DestinationPageIndex` = value + 1 | | 0x13527 | as for page destinations: u32 page (0), f64 zoom, u32 view setting, four f64 | `ViewPercentage`, `ViewSetting`, `ViewBounds` | | 0x1359F | u32 0x13501, u32 1, u32 link UID (class 0x8C42) | `DocumentPath` (below) | Evidence: 643 destinations in two pairs (all pairs). `Self` is the UID. The name is not stored: IDML writes ` - Page [Fixed]`, where the file name is the last part of the linked document's URI (`objects.md`, links), percent-decoded (643 of 643; all have view setting 0, `Fixed`, so the text for other settings is not shown, and the converter writes `Name` only for view setting 0). `DocumentPath` is that path with `/` written as `:`, percent-decoding applied, preceded by a disk volume name and `:` (643 of 643 apart from the volume name, which the INDD does not hold), so the converter leaves it out. The flag byte 1 with an empty name, against 0 or 2 with a stored name for page destinations, suggests the flag marks an automatic name; IDML writes no `NameManually` here. Attribute order: `Self Name DocumentPath DestinationPageIndex ViewSetting ViewPercentage Hidden DestinationUniqueKey`, then `Properties/ViewBounds`. They follow the URL destinations, sorted by key. Hyperlinks of kind 2004 point at them by key (576), and bookmarks by UID (575). In the trustworthy pairs the converter writes all 643 with every value apart from `DocumentPath`, and their hyperlinks apart from `BorderColor` (see the hyperlink appearance). ## Bookmarks (class 0x1354C) **Chunk 0x13547:** flag byte and string (`Name`), u32 (1 for a top-level bookmark, 2 for one inside another), u32 parent (the document, UID 1, or a bookmark), UID list of child bookmarks, u32 destination UID. All 7 bookmarks match on `Name` and `Destination` (the destination's `Self`), and IDML nests each bookmark's children inside it, in the order of the child list (2 top-level bookmarks with 2 and 3 children). Over the 1,072 bookmarks of the later corpus, name, parent and child order match in all. The destination UID can also be a text destination (82 of 82, written `HyperlinkTextDestination/`) or an external page destination (575 of 575, written as its UID). The u32 after the name (0 to 4) grows with nesting but is not the same depth in every file; no attribute matches it. The document's chunk 0x13501 is u32, u16, then UID lists of the text sources, the hyperlinks and the bookmarks, then a fourth list. The converter writes the top-level bookmarks in the order of the bookmark list. Files from InDesign 3.0 and 4.0 lay out chunk 0x13501 differently: it starts with the UID lists, and there are four before anything else: text sources, page destinations, hyperlinks, bookmarks. Evidence: of the 58 distinct 3.0 and 4.0 files, three have the chunk, and the classes of the listed UIDs show the order. In a 3.0 file (little-endian) the first list holds one text source (class 0x13502), the third one hyperlink (0x13501), and the four lists end the chunk. In two 4.0 files (big-endian) the second list holds 8 page destinations (0x13505) and the fourth 8 bookmarks (0x1354C); then come three empty lists, a count of 8 and eight strings, not identified. The 6.0 layout above reads in all 4,075 distinct 6.0–21.x files that have the chunk. InDesign 5.0 files use the 3.0 and 4.0 layout. 18 of the 108 distinct 5.0 files have the chunk, and in all 18 the four lists hold, in order, text sources (classes 0x13502 and 0x13503), destinations (0x13504, 0x13505 and 0x13506), hyperlinks (0x13501) and bookmarks (0x1354C, in 3 files; empty in the others). Read with the 6.0 layout, 17 of them give a list longer than the chunk. The other hyperlink objects of 5.0 files are described below. ## InDesign 5.0 No 5.0 file has an IDML. The following is from the 17 5.0 files with hyperlinks (122 hyperlinks, 118 text sources, 91 page and 18 URL destinations, 7 text destinations, 45 bookmarks); every object parses to the end of its chunk with it. - Page (0x13507), URL (0x13509) and text (0x13508) destination chunks end after the name: there is no key. The converter writes no `DestinationUniqueKey` for them (the schema allows that). - Hyperlink chunk 0x13502: u32 source, u16 0, u16 hidden, u32 destination UID, the same UID again, u32 kind (2000, 2001, 2002 as above), u32 0x13501, flag byte and name. The destination UID is a page destination (104), a URL destination (16) or 0 (2). The converter finds the destination by UID instead of key. - Text destination chunk 0x13526 holds only the owner UID; the owner (class 0x1353C) has chunk 0x1351E, whose u32 at offset 8 is the destination. - Text sources have no chunk 0x1352E and no range tree. Chunk 0x13524 holds two UIDs: a start marker (class 0x13508) and an end marker (class 0x1353B). Both are owned items of the story at the source's first and last character: of 118 sources, 116 start after a return or at the start of the story, and in 113 the character after the end marker's position is a return. The converter takes the extent as start-marker position to end-marker position + 1. This is inferred from the text structure, not checked against an IDML. - Bookmarks use the 6.0 layout (45 of 45 parse). With these rules the 17 files give 121 hyperlinks, 118 text sources, 7 text destinations and 45 bookmarks, with no warnings, and every output validates. ## Order in designmap The schema puts page destinations, URL destinations, external page destinations, page item sources and hyperlinks after the `idPkg:Story` elements, in that order, and bookmarks after them. The converter sorts each kind of destination by key, as the pairs do, and hyperlinks by UID. ## Not converted The pairs have no QR code hyperlinks with an INDD object of the classes above. One pair has a `HyperlinkQRCode`; it is not converted. A text source whose range holds an anchored object is left out with its hyperlink. InDesign writes the anchored `Rectangle` inside the `HyperlinkTextSource` (one source in each of two corpus pairs), but the IDML schema allows no page item there.