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. 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. An entry that sets no note renders no note, and an entry with no label renders no label.

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, which is the entry marked self = true on a site that marks no other:

.. 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.0b4.dev192+gad5d98384). https://documenteer.lsst.io

BibTeX
@software{documenteer,
    author = {Sick, Jonathan},
    title = {{Documenteer}},
    version = {2.5.0b4.dev192+gad5d98384},
    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 that isn’t the site’s own:

.. citation-card:: Paper

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

An entry answers to three names, matched exactly and case-sensitively: its label, its bibtex_key, and its DOI. Each of these renders the same card of 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 selects.

A label is a display string and may repeat; the key and the DOI are unique site-wide, and are what a page selects with when several entries share a heading. An argument two entries answer to renders nothing and warns, naming both by key (see Unresolvable citations).

Copying the BibTeX entry

Below the citation, the card carries a collapsed BibTeX disclosure holding the entry composed from the same metadata, and a Copy BibTeX button that puts it on the clipboard. Copying is what GitHub’s “Cite this repository”, Zenodo, and ADS all offer, and it is what a reader wants: the entry goes into a .bib file they already keep. A guide therefore never generates .bib files of its own, and there is 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 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 is published at — a site at https://dp2.lsst.io composes @dataset{dp2,, and the Software card above is keyed documenteer — and 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. 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 entry is in the page rather than in a script, so it can always be selected and copied by hand. A browser that gives the page no clipboard access — an insecure origin, say — has the button removed and keeps the entry; 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.

This page was last modified on .

https://documenteer.lsst.io/guides/citations/cards.html

On this page