References & Links

References refer to labeled content (e.g. a figure, document or table) and automatically generates links and extra information, like numbering. This page covers the basics of setting up references to content and shows examples for sections, figures, tables and equations.

Directive Targets and Cross References¶

Targets are custom anchors that you can refer to elsewhere, for example, a figure, section, table, program, or proof. To be referenceable, they must have a label/identifier pair in the AST. These can be setup by setting the label or name option in a directive.

Cross-referencing content is accomplished with markdown link syntax ([text](#link)) or through specific roles (ref, numref, eq or doc), depending on your use-case.

Specification¶

In-line reference to an associated node

type: string, (“crossReference”)

See also Node

kind: string, optional, (“eq” | “numref” | “ref”)

Indicates if the references should be numbered.

children: array, optional, (StaticPhrasingContent)

Children of the crossReference, can include text with “%s” or “{number}” and enumerated references will be filled in.

identifier: string

See also OptionalAssociation

label: string, optional

See also OptionalAssociation

position: object, optional, (Position)

See also Node

data: object, optional

See also Node

Example¶

see {numref}`my-table`

```{list-table}  Caption text
:name: my-table

*   - Head 1
*   - Row 1
```

type: root
children:
  - type: paragraph
    children:
      - type: text
        value: 'see '
      - type: mystRole
        name: numref
        value: my-table
        children:
          - type: crossReference
            kind: numref
            identifier: my-table
            label: my-table
  - type: mystDirective
    name: list-table
    args: Caption text
    options:
      name: my-table
    value: |-
      *   - Head 1
      *   - Row 1
    children:
      - type: container
        kind: table
        identifier: my-table
        label: my-table
        children:
          - type: caption
            children:
              - type: paragraph
                children:
                  - type: text
                    value: Caption text
          - type: table
            children:
              - type: tableRow
                children:
                  - type: tableCell
                    children:
                      - type: text
                        value: Head 1
              - type: tableRow
                children:
                  - type: tableCell
                    children:
                      - type: text
                        value: Row 1

Using Markdown Links¶

Using markdown link syntax is one of the most versatile ways to link to content. This uses the standard CommonMark syntax for a link ([text](#link)), and the link can either be a label or a link to a document. For example:

[A **bolded _reference_** to a page](./references.md)
[A reference to a header](#targeting-headers)

Using the {ref} role¶

The {ref} role can be used to bring the title or caption directly in line, the role can take a single argument which is the label:

{ref}`reference-target`

You can also choose the reference text directly (not taking from the title or caption) by using:

{ref}`your text here <reference-target>`

Numbering references with {numref}¶

The {numref} role is exactly the same as the above {ref} role, but also allows you to use a %s in place of the number, which will get filled in when the content is rendered. For example, {numref}`Custom Table %s text <my-table-ref>`. will become Custom Table 3 text. You can try this in the demo above!

Using the {eq} role¶

The {eq}`my-equation` syntax creates a numbered link to the equation, which is equivalent to [](#my-equation) as there is no text content to fill in a title or caption.

Using the {doc} role¶

The {doc}`./my-file.md` syntax creates a link to the document, which is equivalent to [](./my-file.md).

Equations Targets¶

To reference equations, use the {eq} role. It will automatically insert the number of the equation. Note that you cannot modify the text of equation links.

```{math}
:label: my-math-label
e=mc^2
```

See Equation {eq}`my-math-label`!

Target Node¶

Placing a Target node allows you to cross reference the subsequent node by target value.

Specification¶

Target node - provides identifier/label for the following node

type: string, (“mystTarget”)

See also Node

label: string, optional

unresolved target label

position: object, optional, (Position)

See also Node

data: object, optional

See also Node

Example¶

(my_ID)=
# My Header

type: root
children:
  - type: mystTarget
    label: my_ID
  - type: heading
    depth: 1
    children:
      - type: text
        value: My Header

Header Targets¶

To add labels to a header use (my-section)= before the header, these can then be used in markdown links and {ref} roles. This is helpful if you want to quickly insert links to other parts of your book.