DocumenterCitations.jl

DocumenterCitations.jl uses Bibliography.jl to add support for BibTeX citations in documentation pages generated by Documenter.jl.

By default, DocumenterCitations.jl uses a numeric citation style common in the natural sciences, see e.g. the journals of the American Physical Society, and the REVTeX author's guide. Citations are shown in-line, as a number enclosed in square brackets, e.g., "Optimal control is a cornerstone in the development of quantum technologies [1]". Alternative styles are supported, including an author-year style.

Installation instructions

You can install the latest version of DocumenterCitations.jl using the built-in package manager

pkg> add DocumenterCitations

In most cases, you will just want to have DocumenterCitations in the project that builds your documentation (e.g. test/Project.toml). Thus, you can also simply add

DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"

to the [deps] section of the relevant Project.toml file.

Telling Documenter.jl about your bibliography

First, place a BibTeX refs.bib file in the docs/src folder of your project. Then, in docs/make.jl, instantiate the CitationBibliography plugin with the path to the .bib file. Assuming Documenter >= 1.0, pass the plugin object to makedocs as an element of the plugins keyword argument:

using DocumenterCitations

bib = CitationBibliography(
    joinpath(@__DIR__, "src", "refs.bib");
    style=:numeric
)
makedocs(; plugins=[bib], ...)

In older versions of Documenter.jl, bib had to be passed as a positional argument to makedocs.

To use the author-year style that was the default prior to DocumenterCitations version 1.0, replace style=:numeric with style=:authoryear.

Somewhere in your documentation, like a References page, include a markdown block

# References

```@bibliography
```

to insert the bibliography for all cited references in the project. See Syntax for the Bibliography Block for more options.

You will also want to add custom CSS Styling to your documentation to improve the rendering of your bibliography.

Thus, a full docs/make.jl file might look something like this:

using DocumenterCitations
using Documenter
using Pkg

PROJECT_TOML = Pkg.TOML.parsefile(joinpath(@__DIR__, "..", "Project.toml"))
VERSION = PROJECT_TOML["version"]
NAME = PROJECT_TOML["name"]
AUTHORS = join(PROJECT_TOML["authors"], ", ") * " and contributors"
GITHUB = "https://github.com/JuliaDocs/DocumenterCitations.jl"

bib = CitationBibliography(
    joinpath(@__DIR__, "src", "refs.bib"),
    style=:numeric  # default
)

makedocs(;
    authors=AUTHORS,
    sitename="DocumenterCitations.jl",
    format=Documenter.HTML(
        prettyurls=true,
        canonical="https://juliaquantumcontrol.github.io/DocumenterCitations.jl",
        assets=String["assets/citations.css"],
        footer="[$NAME.jl]($GITHUB) v$VERSION docs powered by [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl)."
    ),
    pages=[
        "Home"                   => "index.md",
        "Syntax"                 => "syntax.md",
        "Citation Style Gallery" => "gallery.md",
        "CSS Styling"            => "styling.md",
        "Internals"              => "internals.md",
        "References"             => "references.md",
    ],
    plugins=[bib],
)
deploydocs(; repo="github.com/JuliaDocs/DocumenterCitations.jl.git")

Bibliographies are also supported in PDFs generated via LaTeX. All that is required is to replace format=Documenter.HTML(…) in the above code with format=Documenter.LaTeX(). See docs/makepdf.jl for an example. The resulting PDF files for the DocumenterCitations package are available as attachments to the Releases.

The rendering of the documentation may be fine-tuned using the DocumenterCitations.set_latex_options function. Note that the bibliography in LaTeX is directly rendered for the different styles from the same internal representation as the HTML version. In particular, bibtex/biblatex is not involved in producing the PDF.

How to cite references in your documentation

You can put citations anywhere in your docs, both in the markdown pages and in the docstrings of any functions that are shown as part of the API documentation: The basic syntax is, e.g., [GoerzQ2022](@cite), for a BibTeX key GoerzQ2022 in refs.bib, which will be rendered in the default numeric style as "[2]". See Syntax for Citations for more details.

Clicking on the citations takes you to the bibliography ("References").

Examples

The following is a list of some projects that use DocumenterCitations:

• Oceananigans
• QuantumPropagators
• QuantumControl
• TwoQubitWeylChamber
• QuantumClifford and the parent QuantumSavory organization

Home References

This page cites the following references:

Also see the full bibliography for further references cited throughout this documentation.