Citations

A site that is published with a DOI is that DOI’s landing page, and a landing page is expected to show the reader a complete bibliographic citation with the DOI written as a resolvable https://doi.org/ link. A guide displays its citations in two places:

• The site footer, on every page.

• A citation card, wherever a page asks for one.

Both read the same citations, so the two can never disagree about what the site asks to be cited as.

Declaring the citations

Both surfaces render the citations the site declares in the [[project.citations]] array of documenteer.toml; neither carries bibliographic fields of its own. A site that documents a data release typically declares two citations — the release itself, which this site is the landing page for, and the paper that describes it:

# documenteer.toml

[[project.citations]]
doi = "10.71929/rubin/2570308"
label = "Dataset"
self = true
note = "To be used when citing the DP2 dataset and this documentation."
title = "Data Preview 2"
publisher = "Vera C. Rubin Observatory"
date = 2025-06-30
authors = [{ name = "Vera C. Rubin Observatory" }]

[[project.citations]]
doi = "10.5281/zenodo.1234567"
label = "Paper"
title = "The Data Preview 2 release"
publisher = "Zenodo"
date = 2025-06-30
authors = [{ name = "Vera C. Rubin Observatory" }]

Citation cards

The citation-card directive renders one of the site’s citations as a card carrying the full citation, the citation’s label, and its note. It is the page-level counterpart to the footer citations, and is the right tool for a dedicated “Citing this site” page, or for a section of the home page.

.. citation-card:: [label]

Render one of the site’s [[project.citations]] entries as a card.

The card shows the citation’s label, the full bibliographic citation with the DOI as a https://doi.org/ hyperlink, and the citation’s note. An entry that sets no note renders no note, and an entry with no label renders no label.

Default: the site’s own citation

With no argument, the card renders the entry marked self = true — the work whose DOI landing page this site is:

reStructuredText

.. citation-card::

markdown

:::{citation-card}
:::

With the configuration above, that card reads:

DATASET

Vera C. Rubin Observatory (2025). Data Preview 2. Vera C. Rubin
Observatory. https://doi.org/10.71929/rubin/2570308

To be used when citing the DP2 dataset and this documentation.

Selecting a citation by label

The optional argument is the label of the entry to render, so a page can also show a citation that isn’t the site’s own:

reStructuredText

.. citation-card:: Paper

markdown

:::{citation-card} Paper
:::

Options

class

Additional CSS classes to set on the card.

name

A cross-reference target for the card.

Unresolvable cards

A card that names a label no entry carries — and a card with no argument on a site where no entry is marked self = true — renders nothing and emits a build warning naming the labels the site does declare.

That warning carries the subtype documenteer.citation_card, so a site that knowingly keeps such a card can stop it from failing a warnings-as-errors (-W) build:

# conf.py
suppress_warnings = ["documenteer.citation_card"]

Footer citations

The site footer shows the citations on every page, which is what makes each page of the guide a landing page for the site’s DOI rather than only the page that carries a card.

The footer shows the entry marked self = true and every entry that sets in_footer = true, in the order documenteer.toml declares them. Each one shows the same three parts a card does — the label, the citation with its DOI as a https://doi.org/ hyperlink, and the note — under a “How to cite” heading. With the configuration above, the footer reads:

How to cite

DATASET

Vera C. Rubin Observatory (2025). Data Preview 2. Vera C. Rubin
Observatory. https://doi.org/10.71929/rubin/2570308

To be used when citing the DP2 dataset and this documentation.

A guide that declares no citations, and one whose entries all set in_footer = false, renders no citations block at all.

Related metadata

Declaring [[project.citations]] also makes the site’s DOI machine-readable: every page’s <head> carries the self citation’s DOI as Highwire and Dublin Core meta tags, along with a schema.org JSON-LD description of the site and the works it cites. See [[project.citations]] for the full field reference.