Cross-references & the index

A cross-reference is a hyperlink whose words are generated from its target; an index is built from markers left in the text.

In short A cross-reference has three parts. In the story, a CrossReferenceSource wraps the generated words ("“Results” on page 12") and names a CrossReferenceFormat in AppliedFormat. In the design map, the format lists the BuildingBlocks that make up those words, and a Hyperlink joins the source to its destination, usually a text destination in another story. An index entry is an empty PageReference marker in the text that names a Topic. In both cases the file stores the generated text as ordinary text; the structure records how to rebuild it.

The source: CrossReferenceSource

A CrossReferenceSource sits in a ParagraphStyleRange and wraps the CharacterStyleRanges that hold the generated words. The Content inside is the text InDesign last generated, so a reader that only extracts text gets the phrase as printed.

AppliedFormat names the CrossReferenceFormat that builds the phrase. InDesign drops a cross-reference source that names no format.

Attribute · CrossReferenceSource	Values	Paged	paged.set
AppliedCharacterStyle	reference	not read
Name	reference	read
Self	reference	read

The format: CrossReferenceFormat and BuildingBlock

A CrossReferenceFormat is a direct child of Document in the design map; InDesign writes the formats after the sections, before the story references. It is a recipe: an ordered list of BuildingBlock children, each contributing one piece of the phrase. BlockType says which piece:

These are the six values seen in the census. InDesign writes its default formats into every document it exports: all 271 InDesign-exported documents in the census carry CrossReferenceFormat elements whether or not they use a cross-reference. The format named "Full Paragraph & Page Number", for example, is four blocks: a custom opening quote, the full paragraph, a custom closing quote followed by " on page ", and the page number.

Attribute · BuildingBlock	Values	Paged	paged.set
AppliedCharacterStyle	—	written
AppliedDelimiter	builtin	written
BlockType	BookmarkNameBuildingBlock | CustomStringBuildingBlock | FullParagraphBuildingBlock | PageNumberBuildingBlock | ParagraphNumberBuildingBlock | ParagraphTextBuildingBlock	written
CustomText	builtin / text	written
IncludeDelimiter	false	written
Self	text	written

The join: a Hyperlink

The connection between the source and the place it refers to is an ordinary Hyperlink: Source="CrossReferenceSource/…", with the destination named in a typed <Properties><Destination type="object"> child. The destination is usually a HyperlinkTextDestination marker inside the target paragraph's story, so the cross-reference follows the paragraph wherever it moves. Like other hyperlinks, it goes after the last idPkg:Story reference.

The index: Topic and PageReference

An index has two halves. A topic is a term the finished index lists: a Topic record with a Name and an optional SortOrder that files it under a different spelling (so "1984" can sort as "nineteen eighty-four"). A page reference is an empty PageReference element inside a CharacterStyleRange, at the point in the text that should contribute its page number. It names its term with AppliedTopic (a Topic id) or with an inline TopicName.

Attribute · PageReference	Values	Paged	paged.set
AppliedTopic	reference	read
TopicName	enum	read

The census has only one document with index markers, and the Topic and PageReference shapes above come from generated files. How InDesign itself nests topics in the design map has not been checked against an InDesign export yet.

A generated index is then an ordinary story: one paragraph per topic, with its page numbers, saved as text.

In Paged: a cross-reference source becomes a PDF link to the page its destination lands on after layout, so the link follows a reflow; the words are the saved text, and the format's building blocks are not re-applied. A source saved without a format gets one, InDesign's "Full Paragraph & Page Number". Index markers are read, and Paged can build an index from them: topics grouped without regard to case, sorted by SortOrder or name, with each topic's page labels de-duplicated.

Supported · verified

Frequently asked questions

What is the difference between a cross-reference and a hyperlink? A cross-reference is a hyperlink whose words are generated from the target, using a CrossReferenceFormat. A plain hyperlink's words are whatever the author typed.

Where is the text of a cross-reference stored? Inside the CrossReferenceSource in the story, as ordinary Content. It is the phrase InDesign last generated and goes stale if the destination moves to another page.

What is a BuildingBlock? One piece of a cross-reference format: fixed text, the destination paragraph's text or number, or its page number. A format is an ordered list of them.

Why does every InDesign file contain CrossReferenceFormat elements? InDesign writes its built-in formats into every document, used or not.

How is an index entry marked in the text? With an empty PageReference element at the spot in the story, naming a Topic through AppliedTopic or giving the term inline as TopicName.