References and tooltips

Use the :label: tag to assign a unique label to any part of the manuscript, and use the :ref: tag to refer to it.

:remark: {
  :label: lbl1
}
This remark can be referenced by using
its label.
::

Refer to :ref:lbl1:: above.

Hovering over the link text will display a tooltip showing the referenced region.

By default, the :ref: tag is displayed using the type of region referenced and its number, if it has one; this generates the text “Remark 1” in the preceding example. You can override this behavior when using the :reftext: tag.

:remark: {
  :label: lbl2
  :reftext: Awesome Remark
}
This remark can be referenced by using
its label.
::

Refer to :ref:lbl2:: above.

The :reftext: tag is used at the same place where the :label: tag is defined, and it changes the default text displayed whenever the annotated region is referenced. You can also override the behavior of a single call to :ref: by using the following notation.

:remark: {
  :label: lbl3
}
This remark can be referenced by using
its label.
::

Refer to :ref:lbl3:: above, or call
it :ref:lbl3, Awesome Remark::.

Summary

Use :label: <label> to assign a unique label to a region of the manuscript. Use :ref:<label>:: to reference a region via its label. Override the displayed text globally by using :reftext: <text> at the location where the label is defined, or by using :ref:<label>,<text>:: where the reference is used. Regardless of the displayed text, a reference will display with a tooltip.