README.md

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]."

Alternatively, author-year and alphabetic citations styles are available, see the Citation Style Gallery. Prior to version 1.0, the author-year style was the default, see NEWS.md. It is possible to define custom styles.

Installation

The DocumenterCitations package can be installed with Pkg as

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.

Usage

• 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 element of the plugins keyword argument:

  using DocumenterCitations
  
  bib = CitationBibliography(joinpath(@__DIR__, "src", "refs.bib"))
  makedocs(; plugins=[bib], ...)

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

• Optional, but recommended: add CSS to properly format the bibliography

• Somewhere in your documentation include a markdown block

  ```@bibliography
  ```

  that will expand into a bibliography for all citations in the documentation.

• Anywhere in the documentation or in docstrings, insert citations as, e.g., [GoerzQ2022](@cite), which will be rendered as "[2]" and link to the full reference in the bibliography.

See the documentation for additional information.

Documentation

The documentation of DocumenterCitations.jl is available at https://juliadocs.github.io/DocumenterCitations.jl. In addition to documenting the usage of the package, it also serves as its showcase.