Cross References

Press supports referencing elements within a document by ID, displaying page numbers, and creating citations for academic or technical reports.

Element IDs

Assign a unique identifier to any element with the id attribute:

<h1 id="methodology">Methodology</h1>

Auto-Generated IDs from Markdown

Headings in markdown flows automatically receive a slug-based ID derived from the heading text. For example, # My Heading gets id="my-heading". This means you can reference markdown headings without manually assigning IDs:

<flows>
  <body type="markdown">
    # Methodology

    Details of the approach...
  </body>
</flows>

<!-- Reference the markdown heading elsewhere -->
<p>See <ref id="methodology" /> on page <page-number id="methodology" />.</p>

Duplicate headings receive a numeric suffix (summary, summary-1). See Markdown in Press for the full slugification rules.

Referencing Content

Use <ref /> to display the outline index of a referenced element:

<p>As described in section <ref id="methodology" />, we used a mixed-methods approach.</p>

This renders the index of the element with id="methodology" at the current outline level.

Displaying Page Numbers

Use <page-number /> with an id attribute to display the page where an element appears:

<p>See <ref id="methodology" /> on page <page-number id="methodology" />.</p>

Without an id, <page-number /> displays the current page number:

<frame text-align="center" font-size="9pt">
  Page <page-number /> of <total-pages />
</frame>

The Outline Attribute

The outline attribute registers elements into named collections for iteration:

<h1 outline="sections">Introduction</h1>
<h1 outline="sections">Analysis</h1>
<h1 outline="sections">Conclusion</h1>

These can then be iterated in a table of contents. See the Table of Contents guide. If level is not included, the outline entry is automatically added as a sibling to the current level.

Internal Links

Use the target attribute to create clickable links that navigate to another element's id within the document. This works on both block-level elements (frames) and inline elements (spans).

<h1 id="methodology">Methodology</h1>

<!-- Clicking this frame navigates to the "methodology" heading -->
<frame target="methodology">
  <p>Jump to Methodology</p>
</frame>

Inline elements can also be links:

<p>See the <span target="methodology" font-color="blue">Methodology</span> section.</p>

The target must match the id of an existing element in the document. If no matching id is found, an error is thrown.

Linking with Outline Entries

When iterating over outline entries on a deferred page, you can use {{ entry.id }} to get the element's id and use it as a link target:

<page deferred="true">
  <repeat outline="headings" item="entry">
    <frame target="{{ entry.id }}">
      {{ entry['text-content'] }} ... {{ entry['page-number'] }}
    </frame>
  </repeat>
</page>

This creates a clickable table of contents where each entry links directly to the corresponding heading in the document.

Example: A Technical Report

<press>
  <document format="A4" page-margin="2cm">
    <repeat flow="body">
      <page>
        <flow name="body" />
        <frame v-align="bottom" height="fill" text-align="center" font-size="9pt">
          Page <page-number />
        </frame>
      </page>
    </repeat>
  </document>

  <flows>
    <body>
      <h1 id="intro">Introduction</h1>
      <p>This report presents findings from a three-year environmental
        monitoring programme 1.</p>
      <frame-break />
      <h1 id="method">Methodology</h1>
      <p>Data collection followed established protocols 2. As outlined in the introduction
        (page <page-number id="intro" />), the study covered
        three distinct regions.
      </p>
    </body>
  </flows>
</press>