Syntax

Syntax for Citations

The following syntax is available to create citations in any markdown text:

• [key](@cite) is the basic syntax, e.g., Refs. [GoerzQ2022](@cite) and [Tannor2007](@cite) which is rendered in the default numeric style as "Refs. [2] and [3]".

• [key; note](@cite) allows to include a note in the citation, e.g., See Ref. [GoerzQ2022; Eq. (1)](@cite) which is rendered as "See Ref. [2, Eq. (1)]".

• Multiple keys can be combined in a single citation, e.g., [BrumerShapiro2003, BrifNJP2010, Shapiro2012, KochJPCM2016; and references therein](@cite) renders as "[1, 4–6, and references therein]".

• The direct [text](@cite key) can be used to link to a reference from arbitrary text, e.g., [the Semi-AD paper](@cite GoerzQ2022) renders as "the Semi-AD paper".

In […](@cite), the following variations can be used instead of @cite:

• @citet: Text-style citation. This embeds the citation in the text flow, e.g., "As shown by Goerz et al. [2]…". For the default numeric citations, this is an alternative to "As shown in Ref. [2]"
• @citep: Parenthetical citation. For the built-in styles, this is equivalent to just @cite.
• @citet*: Like @citet, but with the full list of authors, e.g., Goerz, Carrasco and Malinovsky [2].
• @cite*/@citep*: Like @cite/@citep, but with the full list of authors (for non-numeric styles where this makes sense).

Lastly, capitalizing the c in @citet or @citet* ensures that the first letter of the citation is capitalized so that it can be used at the beginning of a sentence, e.g., Von Winckel and Borzì [7] ([WinckelIP2008](@Citet)) versus von Winckel and Borzì [7] ([WinckelIP2008](@citet)).

The natbib commands @citealt, @citealp, and @citenum commands are also recognized. They are not supported by any of the built-in styles, but may be handled by custom styles.

See the Citation Style Gallery for examples of all the possible combinations.

Citations in docstrings

In docstrings, citations can be made with the same syntax as above. However, since docstrings are also used outside of the rendered documentation (e.g., in the REPL help mode), they should be more self-contained.

The recommended approach is to use a # References section in the docstring with an abbreviated bibliography list that links to the main bibliography. For example,

# References

* [GoerzQ2022](@cite) Goerz et al. Quantum 6, 871 (2022)

in the documentation of the following Example:

Example

(cf. the source of the Example type).

If there was no explicit numerical citation in the main text of the docstring,

* [Goerz et al. Quantum 6, 871 (2022)](@cite GoerzQ2022)

rendering as

• Goerz et al. Quantum 6, 871 (2022)

would also have been an appropriate syntax.

Syntax for the Bibliography Block

Default @bibliography block

```@bibliography
```

renders a bibliography for all references that are cited throughout the entire documentation, see Cited References. As of version 1.0, the bibliography will not include entries that may be present in the .bib file, but that are not cited.

Full @bibliography

```@bibliography
*
```

Renders a bibliography for all references included in the .bib file, not just those cited in the documentation. This corresponds to the pre-1.0 default behavior.

Multiple @bibliography blocks

It is possible to have multiple @bibliography blocks. However, there can only be one "canonical" bibliography target for any citation (the location where a citation links to). Any @bibliography block will automatically skip entries that have already been rendered in an earlier canonical @bibliography block. Thus, for two consecutive

```@bibliography
```

blocks, the second block will not show anything.

On the other hand,

```@bibliography
```

```@bibliography
*
```

will first show all the cited references and then all the non-cited references. This exact setup is shown on the References page.

Secondary @bibliography blocks

Sometimes it can be useful to render a subset of the bibliography, e.g., to show the references for a particular page. Two things are required to achieve this:

• To filter the bibliography to a specific page (or set of pages), add a Pages field to the @bibliography block. Exactly like the Pages field in Documenter's @index and @contents blocks, it must evaluate to a list of paths to .md files, relative to the folder containing the current file. The value @__FILE__ as an element in the list can be used to refer to the current file.

• To get around the caveat with multiple @bibliography blocks that there can only be one canonical target for each citation, add Canonical = false to the @bibliography block. The resulting bibliography will be rendered in full, but it will not serve as a link target. This is the only way to have a reference rendered more than once.

For example,

```@bibliography
Pages = ["index.md"]
Canonical = false
```

renders a bibliography only for the citations on the Home page:

Usually, you would have this at the bottom of a page, as in Home References.

Another possibility that is appropriate for Citations in docstrings is to write out a shortened bibliography "by hand".

Explicit references

A non-canonical @bibliography block can also be used to render a bibliography for a few specific citations keys:

```@bibliography
Pages = []
Canonical = false

BrifNJP2010
GoerzDiploma2010
GoerzPhd2015
```

renders a bibliography only for the references BrifNJP2010, GoerzDiploma2010, and GoerzPhd2015:

The Pages = [] is required to exclude all other cited references. Note that the numbers [1, 8, 9] are from the main (canonical) References page.

Order of references

In the default numeric style, references in a @bibliography are rendered (and numbered) in the order in which they are cited. When there are multiple pages in the documentation, the order in which the pages appear in the navigation bar is relevant.

Non-cited references (* in a full bibliography) will appear in the order they are listed in the underlying .bib file. That order may be changed by sorting it explicitly:

bib = CitationBibliography("refs.bib")

using Bibliography
sort_bibliography!(bib.entries, :nyt)  # name-year-title

In general, the citation style determines the order of the references, see the Citation Style Gallery.

Syntax for the .bib file

The refs.bib file is in the standard BibTeX format. It must be parsable by BibParser.jl.

Even in LaTeX, you cannot blindly use .bib entries exported from a bibliography manager. All .bib files must be curated by hand! This is true even more so for a project using DocumenterCitations. A .bib file that works well with LaTeX will usually, but not always work well with DocumenterCitations: Remember that in LaTeX, the strings inside any BibTeX fields are rendered through the TeX engine. At least in principle, they may contain arbitrary macros.

In contrast, DocumenterCitations only parses a subset of LaTeX syntax and converts it to markdown. This includes the commands for special symbols (although unicode is preferred) and a handful of commands like \url and \href. If you would like to have support added for a specific additional command, please open an issue. In addition, DocumenterCitations recognizes and preserves in-line math and removes braces.

"Any .bib file will render the bibliography you expect" is not a design goal. Instead, DocumenterCitations tries to ensure that

1. It is possible to write a .bib file that produces the expected results; and
2. Most reasonably clean (hand-curated) .bib files that work with BibTeX also work with DocumenterCitations.

Some tips to keep in mind when editing a .bib file to be used with DocumenterCitations:

• Use unicode instead of escaped symbols. Nowadays, bibtex/pdflatex seems to handle unicode without problems, so it's best to keep your .bib files in unicode.
• You do not need to use braces to protect capitalization. Unlike bibtex, DocumenterCitation will preserve the capitalization of titles. You should always put the title in the .bib file as it appears in the published paper.
• Use a consistent scheme for citation keys. Shorter keys are better.
• All entries should have a Doi field, or a Url field if no DOI is available.
• When citing websites [10], in addition to the Url field, a Urldate field may be given in the format YYYY-MM-DD. This will be rendered as, e.g., "Accessed on Oct 24, 2023".
• Use @string macros for abbreviated journal names, with the caveat of #31 and #32 in the BibParser.jl issues.

You may be interested in using (or forking) the getbibtex script to generate consistent .bib files.

Preprint support

If the published paper (Doi link) is not open-access, but a version of the paper is available on a preprint server like the arXiv, your are strongly encouraged to add the arXiv ID as Eprint in the BibTeX entry. In the rendered bibliography, the preprint information will be shown and automatically link to https://arxiv.org/abs/<ID>. If necessary, you may also add a Primaryclass field to indicate a category, see "BibTeX and Eprints" in the arXiv documentation.

Note that unlike in default BibTeX, it is not necessary to define Archiveprefix in the .bib file. A missing Archiveprefix is assumed to be arXiv. The field name Eprinttype (which in BibTeX is an alias for Archiveprefix) is currently not yet supported, nor is Eprintclass as an alias for Primaryclass.

For documents that are available only as an arXiv eprint, the best result is obtained with a BibTeX entry using the @article class, with, e.g., arXiv:2003.10132 in the Journal field, and, e.g., 10.48550/ARXIV.2003.10132 in the Doi field (but no Eprint field) [11].

Beyond arXiv, other preprint servers are supported. The Archiveprefix field for non-arXiv preprints is mandatory. For any defined Archiveprefix, Eprint, and Primaryclass fields, the rendered bibliography will include the preprint information in the format ArchivePrefix:Eprint [Primaryclass]. However, only certain preprint servers (known ArchivePrefix) will automatically be linked. Besides arXiv, the currently supported preprint servers are:

• BiorXiv. The Archiveprefix is biorXiv. The Eprint ID should be the final part of the DOI, e.g. 2022.09.09.507322 [12].
• HAL. The Archiveprefix is HAL. The Eprint ID should include the prefix (usually hal-, but sometimes tel-, etc.), e.g., Refs. [13, 14].

If you would like support for any additional preprint server, please open an issue.