Links, citations, and cross-references¶

Markdown supports a range of different links to locations both within and outside the site.

External links¶

References are of the form [text](URL) but MyST also supports just providing the <URL>. The former structure hides the URL, the latter shows it: https:open.ac.uk. If the link points to a page outside of the materials, then this is visually highlighted by the inclusion of an icon.

Internal links¶

To link to other pages of the same website, the URL must be the path of the linked file, relative to the file with the link: [text](path/to/other-file.md).

For example: [homepage](../../index.md) produces a link to this site’s homepage.

If the text is left out, as in [](path/to/other-file.md), MyST uses the file’s level 1 heading.

Example: [](../../index.md) produces a link to OU Book Theme.

Interal links to sections¶

To link to a section of a webpage, write [text](path/to/file.md#heading), with the section’s heading in lowercase and with hyphens instead of spaces.

For example, to link to the Horizontal lines section in the block text markup, write [Horizontal lines](images.md#horizontal-lines). If the link is to a section on the same page, then just leave out the filename.

Download links¶

If the relative path is to a file that hasn’t the .md extension, then a download icon will precede the link. The file name is displayed when no link text is given. For example, [](images/ido_250.png) produces images/ido_250.png, while [configuration file](../../conf.py) produces configuration file.

Citations and bibliography¶

Citations and a bibliography are supported using the sphinxcontrib-bibtex extension.

For this to work, you must add the following two lines into the conf.py configuration file:

bibtex_bibfiles = ["references.bib"]
bibtex_reference_style = "author_year"

and then add a references.bib file to the content folder. Any reference that is to be cited must be added to that file in BibTeX format.

Citations can then be added using either {cite:p}`brandl2021sphinx`, which produces [Brandl, 2021], or using {cite:t}`brandl2021sphinx`, which produces Brandl [2021].

Citations will only appear after you have defined where the bibliography is to be shown. To define the bibliography, add the following code block where you want the bibliography to be shown:

:::{bibliography}
:::

This produces the following output:

[Bra21] (1,2)

Georg Brandl. Sphinx documentation. URL http://sphinx-doc.org/sphinx.pdf, 2021. URL: http://sphinx-doc.org/sphinx.pdf.

Cross-references¶

Where you have used :name: to add specific identifiers to figures, tables, or code blocks, you can refer to them using the same structure as when linking to sections: [text](path/to/file.md#name). For [mathematics](../blocks/mathematics.md) equations, you need to link to #label-identity`.

For example [poor documentation code example](code.md#poor-doc) will create a link to the poor documentation code example.

In addition, you can also use numbered references using the {numref} role. To use that use the {numref} role with the name or label of the element you are referring to: {numref}`name-or-label`. For example {numref}`poor-doc` will create the following cross-reference: Listing 1.