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’s the page-level counterpart to the footer citations, and suits a dedicated “Citing this site” page or a section of the home page. Every card on this page is rendered from this site’s own citations.

.. citation-card:: [selector]#

Render one of the site’s [[project.citations]] entries as a card. The optional argument selects the entry by its label, its BibTeX key, or its DOI. With no argument, the card renders the site’s preferred citation.

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. The card omits the note or the label when the entry doesn’t set one.

Default: the site’s preferred citation

With no argument, the card renders the site’s preferred citation: the work the site asks readers to cite. On a site that marks no entry preferred, that’s the entry marked self = true:

.. citation-card::
:::{citation-card}
:::

On this site the preferred citation is Documenteer itself, read from the repository’s CITATION.cff file, so that card renders as:

Software

Sick, Jonathan. Documenteer (version 2.5.0b6.dev7+g51839207b). https://documenteer.lsst.io

BibTeX
@software{documenteer,
    author = {Sick, Jonathan},
    title = {{Documenteer}},
    version = {2.5.0b6.dev7+g51839207b},
    url = {https://documenteer.lsst.io}
}

Cite the version of Documenteer you used; this site documents the version shown.

The citation ends in a link to the software’s landing page rather than to doi.org, because the entry is located by a URL. The version is the one this build of the site documents (see Citing software from CITATION.cff).

Selecting a citation

The optional argument names the entry to render, so a page can also show a citation other than the preferred one:

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

An entry can be selected by any of three names, matched exactly and case-sensitively: its label, its bibtex_key, and its DOI. Each of these renders the same card for this site’s paper:

.. citation-card:: Paper

Paper

Sick, Jonathan; Economou, Frossie (2025). The Documentation Developer Experience: Documentation Engineering at the Vera C. Rubin Observatory. Astronomical Society of the Pacific. https://doi.org/10.26624/XWGH8202

BibTeX
@article{2025ASPC..541..151S,
    author = {Sick, Jonathan and Economou, Frossie},
    title = {{The Documentation Developer Experience: Documentation Engineering at the Vera C. Rubin Observatory}},
    year = {2025},
    publisher = {Astronomical Society of the Pacific},
    doi = {10.26624/XWGH8202},
    url = {https://doi.org/10.26624/XWGH8202}
}

Cite this paper when describing how Rubin Observatory builds its documentation.

.. citation-card:: 2025ASPC..541..151S

Paper

Sick, Jonathan; Economou, Frossie (2025). The Documentation Developer Experience: Documentation Engineering at the Vera C. Rubin Observatory. Astronomical Society of the Pacific. https://doi.org/10.26624/XWGH8202

BibTeX
@article{2025ASPC..541..151S,
    author = {Sick, Jonathan and Economou, Frossie},
    title = {{The Documentation Developer Experience: Documentation Engineering at the Vera C. Rubin Observatory}},
    year = {2025},
    publisher = {Astronomical Society of the Pacific},
    doi = {10.26624/XWGH8202},
    url = {https://doi.org/10.26624/XWGH8202}
}

Cite this paper when describing how Rubin Observatory builds its documentation.

.. citation-card:: 10.26624/XWGH8202

Paper

Sick, Jonathan; Economou, Frossie (2025). The Documentation Developer Experience: Documentation Engineering at the Vera C. Rubin Observatory. Astronomical Society of the Pacific. https://doi.org/10.26624/XWGH8202

BibTeX
@article{2025ASPC..541..151S,
    author = {Sick, Jonathan and Economou, Frossie},
    title = {{The Documentation Developer Experience: Documentation Engineering at the Vera C. Rubin Observatory}},
    year = {2025},
    publisher = {Astronomical Society of the Pacific},
    doi = {10.26624/XWGH8202},
    url = {https://doi.org/10.26624/XWGH8202}
}

Cite this paper when describing how Rubin Observatory builds its documentation.

The DOI is also accepted as doi:10.26624/XWGH8202 and as https://doi.org/10.26624/XWGH8202, so a DOI copied from anywhere works.

A label is a display string and may repeat. The key and the DOI are unique site-wide, so use one of them when several entries share a label. An argument that matches two entries renders nothing and emits a warning that names both by key (see Unresolvable citations).

Copying the BibTeX entry

Below the citation, the card carries a collapsed BibTeX disclosure holding the BibTeX entry composed from the same metadata, and a Copy BibTeX button that copies it to the clipboard. GitHub’s “Cite this repository” button, Zenodo, and ADS all offer copying, and it matches how readers work: the entry goes into a .bib file they already keep. A guide therefore never generates .bib files of its own, and there’s nothing to download.

The entry type follows the citation’s type, so a copied entry says what the work is instead of filing everything under @misc: type = "dataset" composes @dataset, "article" composes @article, "software" composes @software, and "report" composes @techreport. A citation typed "other", and one that declares no type at all, composes as @misc.

A @software or @dataset entry also carries a version field when the citation states a version. Those are the two entry types that biblatex defines the field on, and the others omit it. The entry’s key never carries the version, so a reader’s .bib file keeps working when the cited software is released again.

Citation keys

Every entry is keyed by something a reader already recognizes. The site’s own work is keyed by the lsst.io subdomain it’s published at: a site at https://dp2.lsst.io composes @dataset{dp2,, and the Software card above is keyed documenteer. Every other work that has a DOI is keyed by the DOI, @misc{10.71929/rubin/3382528,, which is how lsst.bib keys its DataCite records. A work with neither falls back to author, year, and title (jenness2022vera).

Those keys are stable: neither a subdomain nor a DOI changes when the site is rebuilt or released again, so a manuscript that copied an entry keeps citing the same key. A site that needs a particular key (the RTN-115 an existing bibliography already uses, or the ADS bibcode a paper is indexed under) pins it with bibtex_key. This site pins its paper’s key to its bibcode, which is why the Paper card above is keyed 2025ASPC..541..151S rather than by its DOI:

[[project.citations]]
doi = "10.26624/XWGH8202"
bibtex_key = "2025ASPC..541..151S"

See bibtex_key for the full rules, including what happens when two entries would take the same key.

The BibTeX entry is part of the page’s HTML rather than generated by a script, so it can always be selected and copied by hand. When a browser gives the page no clipboard access (on an insecure origin, for example), the button is removed and the entry stays. A page whose scripts never load keeps both. A non-HTML builder renders the entry as a plain literal block, since a disclosure and a button mean nothing there.

An edit to [[project.citations]] reaches every card on the next build, which re-reads every page. See An edit to the citations did not appear.

Options

class

Additional CSS classes to set on the card.

name

A cross-reference target for the card.