Inline DOI links#

A card is a block, so a page that only needs to mention a work — the first bullet of an access list, a cell in a table of data products, a sentence pointing at the paper — cannot use one. The doi role links a declared citation’s DOI inline instead, reading the same [[project.citations]] entries the card and the footer do. A page that would otherwise write https://doi.org/10.26624/XWGH8202 into a sentence by hand, or into a substitution that holds it, names the entry and gets whatever the configuration declares. The links on this page are rendered from this site’s own citations.

:doi:#

Link one of the site’s [[project.citations]] entries by its DOI.

The role’s content names the entry, resolved the same way the citation-card directive’s argument is: by label, by bibtex_key, or by DOI in any spelling, matched exactly and case-sensitively. The link’s text is the resolvable https://doi.org/ URL, the form the Crossref and DataCite display guidelines ask for:

reStructuredText

The paper is published as :doi:`Paper`.

markdown

The paper is published as {doi}`Paper`.

That sentence renders as: The paper is published as https://doi.org/10.26624/XWGH8202.

Selecting by BibTeX key renders the same link: https://doi.org/10.26624/XWGH8202 is written :doi:`2025ASPC..541..151S`.

Custom link text

The standard text <target> spelling puts your own words on the link, for a sentence that should read as prose rather than as an identifier:

reStructuredText

For the background see :doi:`the ADASS paper <Paper>`.

markdown

For the background see {doi}`the ADASS paper <Paper>`.

That sentence renders as: For the background see the ADASS paper.

It is also what lets a sentence display one word over an entry it selects unambiguously, which is how a site whose products all need the word “TAP” writes them:

* TAP: :doi:`TAP <10.71929/rubin/3382540>`

Where it works

The role renders one external hyperlink and nothing else, so it composes wherever inline markup does: a sentence, a list item, a table cell, and the body of a replace substitution definition. A data product’s “Access” list is the case it was added for:

Access
------

* DOI: :doi:`Object catalog`
* TAP table name: ``dp02_dc2_catalogs.Object``

.. |dp2_paper| replace:: :doi:`the DP2 paper <Paper>`

There is no default entry: the role always names one. A role appears mid-sentence, where an implicit subject would be a guess at which of the site’s works the sentence is about.

The role is a link, and only a link — no note, no BibTeX entry, no author-year text. A page that is a work’s landing page should therefore carry a card for it and use the role only for short references elsewhere, since the card is what shows a reader the full citation and the entry they came for.

An entry located by a url rather than a DOI, such as this site’s own Software entry, cannot be linked with the role, because the link’s text would not be a DOI; the build warns (see Unresolvable citations). Link such a work with ordinary hyperlink syntax, or show it with a card.

Citing works that are not among the site’s own declared citations — a bibliography of the literature a guide discusses — is not what this role is for, and is not yet supported.