DocumenterCitations.jl is a Documenter.jl plugin to add BibTeX citations to your documentation.
By default, DocumenterCitations.jl uses a numeric citation style common in the natural sciences. 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].”
![Rendered bibliography of two references, [1] and [2]](https://global.discourse-cdn.com/julialang/original/3X/b/7/b764ed00c0eaa6b3125a0ac53a786d9dd8a8def5.png)
Alternatively, author-year and alphabetic citations styles are available. It is also possible to define custom styles.
The project recently became part of the JuliaDocs organization and is now available in its first “stable” version 1.0.
Usage
-
Place a BibTeX
refs.bibfile in thedocs/srcfolder of your project. Then, indocs/make.jl, instantiate theCitationBibliographyplugin and pass it tomakedocs:using DocumenterCitations bib = CitationBibliography(joinpath(@__DIR__, "src", "refs.bib")) makedocs(bib, ...) -
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 and especially the Syntax section for details.
New Features
From the release notes for the 1.0 release:
CitationBibliographynow takes astylekeyword argument. The default style isstyle=:numeric. Other built-in styles arestyle=:authoryear(corresponding to the pre-1.0 default) andstyle=:alpha.- It is now possible to implement custom citation styles.
- The
@bibligraphyblock can now have additional options to customize which references are included, see Syntax for the Bibliography Block. - It is possible to generate secondary bibliographies, e.g., for a specific page.
- There is new syntax to create links to bibliographic references with arbitrary text.
- The following variations of the
@citecommand are now supported:@citet,@citep,@cite*,@citet*,@citep*,@Citet,@Citep,@Cite*,@Citet*,@Citep*. See the syntax for citations for details. - Citations can now include notes, e.g.,
See Ref. [GoerzQ2022; Eq. (1)](@cite).
Upgrading from DocumenterCitations v0.2.12
The most notable breaking change in the 1.0 release relative to the previous version 0.2.12 is that the default citation style has changed from author-year to numeric.
As an existing user of the DocumenterCitations plugin, you should add an explicit style=:authoryear keyword argument when instantiating the plugin in your docs/make.jl file:
using DocumenterCitations
bib = CitationBibliography(
joinpath(@__DIR__, "src", "refs.bib");
style=:authoryear
)
makedocs(bib, ...)
In the long term, you may find the default :numeric style preferable, as it is much more common in many of the fields where Julia is most used. However, you will likely have to rephrase parts of your documentation slightly to switch from an author-year style to a numeric style. The @citet and @citet* syntax may be helpful for the transition, as well as the ability to have arbitrary link text.
If you are using DocumenterCitations in your project, consider opening a pull request to add a link to the list of examples.
For any feature requests, please don’t hesitate to open an issue.