lgoettgens/DocumenterCitations.jl

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

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.