Skip to main content
Participating Frequently
May 9, 2025
Question

Resolve internal hyperlinks across multiple ICML files

  • May 9, 2025
  • 2 replies
  • 530 views

I have a project with multiple ICML files (generated via Pandoc, plus some additional scripting), with internal hyperlink references between files—so one file might define an anchor like:

<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Header2">
  <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
    <HyperlinkTextDestination Self="HyperlinkTextDestination/#substrates" Name="#substrates" DestinationUniqueKey="2394463933"/>
    <Content>Substrates</Content>
  </CharacterStyleRange>
</ParagraphStyleRange>

and another file reference it like:

  <HyperlinkTextSource Self="htss-16" Name="#substrates" Hidden="false">
    <CharacterStyleRange AppliedCharacterStyle="CharacterStyle/Link">
      <Content>Substrates</Content>
    </CharacterStyleRange>
  </HyperlinkTextSource>

  <!-- ... -->

  <Hyperlink Self="uf-16" Name="#substrates" Source="htss-16" Visible="false" DestinationUniqueKey="2394463933">
    <Properties>
      <BorderColor type="enumeration">Black</BorderColor>
      <Destination type="object">HyperlinkTextDestination/#substrates</Destination>
    </Properties>
  </Hyperlink>

This all seems to work fine, if the <HyperlinkTextDestination> appears earlier than the <Hyperlink>.

 

But if a <Hyperlink> in an earlier file refers to a <HyperlinkTextDestination> defined in a later file, InDesign doesn't seem to know what to do with it — it rewrites the <Destination> of the <Hyperlink> to point to the first <HyperlinkTextDestination> it knows about, and I end up with a dozen links all pointing to the same (wrong) destination early in the document.

 

I've tried using <CrossReferenceSource> instead of <HyperlinkTextSource> and it seems to be broken in the same way (as well as causing additional problems like spurious out-of-date cross reference warnings that can't be cleared).

 

Is there a workaround for this? If I could somehow explicitly reference the destination ICML file in the link, would InDesign be smart enough to resolve that? Or is this just not possible unless all the links are internal to the same ICML file?

2 replies

Joel Cherney
Community Expert
Community Expert
May 9, 2025

I have a project with multiple ICML files (generated via Pandoc, plus some additional scripting)

 

love pandoc. But sometimes its command of ICML is imperfect. What's your input format, and how are the files being post-processed, with what kind of scripting? (Edit: I totally misread your question) Because I can easily imagine part of your post-processing routine being "run script that parses ICML files as raw text, extracts correct HyperlinkDestinations for each hyperlink and fixes them in InDesign" being a halfway-decent post-processing workaround. 

chronodmAuthor
Participating Frequently
May 9, 2025

I can see that being the issue if it was about using a HyperlinkURLDestination from a later file for a link in an earlier file, but for HyperlinkTextDestination, doesn't it need to be at the spot in the text you want to link to?

chronodmAuthor
Participating Frequently
May 9, 2025

(Some discussion here: https://github.com/jgm/pandoc/issues/5541. I think the current out-of-the-box behavior - which still uses HyperlinkTextSource, not CrossReferenceSource as discussed there - works if all the links are internal to one ICML file.)

Robert at ID-Tasker
Legend
May 9, 2025

Just brainstorming - can't you change import order of ICML files? 

 

chronodmAuthor
Participating Frequently
May 9, 2025

I don't think so - as far as I can tell, InDesign loads them in the order they're placed in the document. Also, at least in theory there could be circular references (a link from an earlier file to an anchor in a later file, which has a link to an anchor in the earlier file). Nice thought, though.

Robert at ID-Tasker
Legend
May 9, 2025

To be honest - I don't have much experience with ICML files - but if you can share - privately if you prefer, please click my nickname - some sample files - I can try to find the solution.