References notes and floats/Visual debugging

When a document contains many cross-references, it can be difficult to see where a reference target is actually defined and where that target is later invoked.

ConTeXt provides several debugging facilities for this purpose.

The most convenient command is:

\showreferences

It displays the names of reference targets and the names of the references that invoke them.

More detailed trackers can also display the actual PDF target and link areas.

\startsection
  [title={First section},
   reference={sec:first}]

\in{section}[sec:first]

1. What is being visualized?

The basic model is:

target side                         reference side

reference={sec:first}               \in{section}[sec:first]
        |                                      |
        v                                      v
   destination                         reference invocation
        |                                      |
        v                                      v
 nodes.destinations                  nodes.references

The debugging facilities can show either the names of these objects or their actual areas in the composed page.

                         visual debugging
                                |
                 +--------------+--------------+
                 |                             |
              labels                         areas
                 |                             |
       +---------+---------+         +---------+---------+
       |                   |         |                   |
destinations.show   references.show  destinations       references
       |                   |         |                   |
 target name         invocation name target area        link areas

This distinction is useful because the textual labels and the actual PDF interaction areas answer different debugging questions.

2. A minimal example with \showreferences

The following example defines one section target and refers to it twice:

\setupinteraction
  [state=start]

\showreferences

\starttext

\startsection
  [title={First section},
   reference={sec:first}]

This is the reference target.

\stopsection

See \in{section}[sec:first]
on \at{page}[sec:first].

\stoptext

With current LuaMetaTeX, the diagnostic display shows approximately:

sec:first      1 First section

               This is the reference target.

               See |sec:first section 1
               on  |sec:first page 1.

The exact placement depends on the surrounding typography.

The important distinction is:

• sec:first identifies the destination ;
• |sec:first identifies a reference invocation .

\enabletrackers
  [nodes.references.show,
   nodes.destinations.show]

3. Showing only destinations or only reference invocations

The two textual trackers can be enabled independently.

3.1 Destination names only

\enabletrackers
  [nodes.destinations.show]

This displays the names of reference targets where they are defined.

For the minimal example above, this displays:

sec:first

near the section target, but does not display the two |sec:first invocation labels.

3.2 Reference invocations only

\enabletrackers
  [nodes.references.show]

This displays the reference names where they are invoked.

For the minimal example, the two calls

\in{section}[sec:first]
\at{page}[sec:first]

are marked by two |sec:first labels, while the destination name itself is not displayed.

4. Showing the actual target and link areas

The trackers without .show serve a different purpose:

\enabletrackers
  [nodes.references,
   nodes.destinations]

Instead of printing the reference names, these trackers mark the actual reference and destination areas graphically.

This is especially useful when inspecting the regions that become PDF links and link targets.

4.1 Destination areas only

\enabletrackers
  [nodes.destinations]

This highlights the destination area itself.

For a section reference, the marked region may cover the section heading where the destination is attached.

4.2 Reference areas only

\enabletrackers
  [nodes.references]

This highlights the clickable reference areas created by commands such as \in and \at.

The log also reports the backend attributes being resolved, for example:

backend > references   > resolving attribute 1
backend > references   > resolving attribute 2
backend > destinations > resolving attribute 1

5. Adjusting the diagnostic labels

The textual diagnostic labels can overlap ordinary document content, especially in a dense layout.

Numeric values may be supplied to the .show trackers:

\enabletrackers[nodes.references.show=2.5]
\enabletrackers[nodes.destinations.show=1]

These values affect the placement of the diagnostic labels.

Their effect depends on the surrounding layout and body font. Larger values may themselves cause labels to intrude into the text or affect line breaking.

6. The references-show system module

ConTeXt also provides the system module:

\usemodule[references-show]

In the LuaMetaTeX version tested during this revision, the module is still distributed as:

s-references-show.mkiv

and loads normally with:

\usemodule[references-show]

The module provides the reference-name visualization and adds a page-level summary box.

A minimal two-page example is:

\setupinteraction
  [state=start]

\usemodule[references-show]

\starttext

\startsection
  [title={First section},
   reference={sec:first}]

This is the first reference target.

\stopsection

See \in{section}[sec:first]
on \at{page}[sec:first].

\page

\startsection
  [title={Second section},
   reference={sec:second}]

This is the second reference target.

See also \in{section}[sec:first].

\stopsection

\stoptext

The summary is normally placed near the upper outer corner of the page.

7. What the module summary box contains

The wording used in older documentation can be misleading here.

The summary box does not list all reference invocations that occur on the page.

It lists the reference targets defined on that page.

This can be seen with the following three-page test:

\setupinteraction
  [state=start]

\usemodule[references-show]

\starttext

\startsection
  [title={First section},
   reference={sec:first}]

This target is defined on page 1.

\stopsection

\page

This page defines no new reference target.

It only refers back to
\in{section}[sec:first]
on \at{page}[sec:first].

\page

\startsection
  [title={Second section},
   reference={sec:second}]

This target is defined on page 3.

It also refers back to
\in{section}[sec:first].

\stopsection

\stoptext

The result is conceptually:

Page 1
    destination defined: sec:first

    summary:
        1 references
        sec:first


Page 2
    no destination defined
    two invocations of sec:first

    summary:
        no references


Page 3
    destination defined: sec:second
    one invocation of sec:first

    summary:
        1 references
        sec:second

So:

reference target defined on page
             |
             v
     appears in summary box


reference invocation on page
             |
             v
     does not appear in summary box

8. References are not limited to sections

Reference debugging works with many kinds of structured objects.

For example:

\setupinteraction
  [state=start]

\showreferences

\starttext

\startsection
  [title={Mixed reference targets},
   reference={sec:mixed}]

This section contains several kinds of reference targets.

\placeformula[eq:square]
\startformula
(a+b)^2=a^2+2ab+b^2
\stopformula

See \in{formula}[eq:square]
on \at{page}[eq:square].

\startitemize[n]

\item[it:first]
This is the first referenced item.

\item[it:second]
This is the second referenced item.

\stopitemize

See \in{item}[it:second]
on \at{page}[it:second].

\startplacefigure
  [title={A dummy figure},
   reference={fig:dummy}]
  \framed
    [width=5cm,
     height=2cm,
     align=middle]
    {Dummy figure}
\stopplacefigure

See \in{figure}[fig:dummy]
on \at{page}[fig:dummy].

See also \in{section}[sec:mixed]
on \at{page}[sec:mixed].

\stopsection

\stoptext

This example contains five destinations:

sec:mixed
eq:square
it:first
it:second
fig:dummy

Only four of them are subsequently invoked.

This is a useful reminder that:

defining a destination
        !=
invoking that destination

A target may exist even when nothing in the document currently points to it.

9. Interaction and debugging are separate

Reference debugging does not create the reference structure itself.

For example:

\setupinteraction
  [state=start]

enables interactive PDF behaviour, while:

\showreferences

adds diagnostic information.

The reference target and reference invocation exist independently of whether their debugging display is enabled.

10. Older trace commands

Older versions of this page listed the following commands without explanation:

\tracebookmarks
\tracelinenotes
\tracereferences
\tracelabels

They should not be treated as current reference-debugging commands.

In the LuaMetaTeX version tested during this revision:

\tracebookmarks      not defined
\tracelinenotes      defined
\tracereferences     not defined
\tracelabels         not defined

\tracelinenotes belongs to line-note diagnostics rather than cross-reference diagnostics and is therefore outside the scope of this page.

11. Troubleshooting

No diagnostic names appear

First verify that the reference itself works normally.

For example:

\startsection
  [title={First section},
   reference={sec:first}]

...

See \in{section}[sec:first].

Then add:

\showreferences

If the ordinary reference does not resolve, the problem is not the visual-debugging layer.

I see the target name but no invocation name

If only:

\enabletrackers[nodes.destinations.show]

is active, this is expected.

Use:

\enabletrackers
  [nodes.references.show,
   nodes.destinations.show]

or simply:

\showreferences

I see names, but I need to inspect the clickable area

Use the low-level tracker:

\enabletrackers[nodes.references]

For destination areas:

\enabletrackers[nodes.destinations]

Diagnostic labels overlap my text

This is normal in some layouts. These labels are development aids and are not intended for the final document.

Numeric tracker values can alter their placement, but such adjustments are layout-dependent.

The references-show box says “no references” even though the page contains links

This is expected if the page contains reference invocations but defines no new reference targets.

The page summary reports targets defined on the page.

12. Tested behaviour

The examples and distinctions on this revision were checked locally with:

ConTeXt 2026.07.29 LMTX
LuaMetaTeX 2.11.09

The tests covered:

• native section references;
• \showreferences ;
• nodes.destinations.show ;
• nodes.references.show ;
• nodes.destinations ;
• nodes.references ;
• numeric .show values;
• the references-show system module;
• page-level module summaries;
• section, formula, item, and figure targets.

13. Related pages

• References — overview of native ConTeXt references and cross-references
• References, notes and floats — overview of the documentation area
• URLs and external links — URLs and external-link mechanisms
• Cross Referencing module — third-party crossref module; distinct from ConTeXt's native reference system
• paragraph-level referencing
• Project structure — products, components, and larger document structures
• \showreference
• \setupinteraction
• \in
• \at