.docname {Cross references}
.include {docs}

In typesetting, cross-references are references to other parts of the document, such as figures, tables, sections, and equations.

In Quarkdown, you create a cross-reference using the **`.ref {id}`** function, where `id` is the cross-reference ID of the target element. The function can appear either before or after the target element.

> Note: Cross-referencing works best when elements are numbered, and you have set a supported document language.
> See [Numbering](numbering.qd) and [Localization](localization.qd) for details.

You typically set the ID using the `{#id}` syntax. The exact location depends on the element type, as the following sections explain.

### Sections

.exampleoutput {![Sections](cross-references/section-reference.png)}
    Once you install Quarkdown, check out .ref {getting-started} for a quick guide.

    ## Getting started {#getting-started}

> Tip: In HTML rendering, the reference ID of headings also becomes the HTML `id` attribute, which makes them suitable for linking.


### Figures

.exampleoutput {![Figures](cross-references/figure-reference.png)}
    The Quarkdown logo is shown in .ref {logo}.

    ![Logo](icon.svg "The Quarkdown icon") {#logo}

### Tables

.exampleoutput {![Tables](cross-references/table-reference.png)}
    As shown in .ref {data}, coffee is the most popular beverage.

    | Person  | Beverage |
    |---------|----------|
    | Alice   | Tea      |
    | Bob     | Coffee   |
    | Charlie | Coffee   |
    {#data}

.example
    With a [caption](table-caption.qd):

    ```markdown
    | Person  | Beverage |
    |---------|----------|
    | Alice   | Tea      |
    | Bob     | Coffee   |
    | Charlie | Coffee   |
    "Beverage preferences" {#data}
    ```

### Equations

.exampleoutput {![Equations](cross-references/equation-reference.png)}
    Einstein's famous equation is shown in .ref {energy}.

    $ E = mc^2 $ {#energy}

.example
    For multi-line equations:

    ```markdown
    $$$ {#energy}
    E = mc^2
    $$$
    ```

> Tip: See [TeX Formulae](tex-formulae.qd) for more information on writing equations in Quarkdown.

### Code blocks (listings)

.exampleoutput {![Code blocks](cross-references/codeblock-reference.png)}
    See the main function in .ref {main}.

    ```kotlin {#main}
    fun main() {
        println("Hello, World!")
    }
    ```

.example
    With a [caption](code-caption.qd):

    ~~~markdown
    ```kotlin "Hello World in Kotlin" {#main}
    fun main() {
        println("Hello, World!")
    }
    ```
    ~~~

### Custom numbered elements

> The `.numbered` function is explained in detail in [Numbering](numbering.qd#custom-numbered-elements).

.exampleoutput {![Custom numbered elements](cross-references/numbered-reference.png)}
    In Example .ref {my-example} you can see a custom numbered element.

    .numbered {examples} ref:{my-example}
        number:
        **Example .number:** this is a custom numbered element.