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 .”
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
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 “” and link to the full reference in the bibliography.
From the release notes for the 1.0 release:
CitationBibliographynow takes a
stylekeyword argument. The default style is
style=:numeric. Other built-in styles are
style=:authoryear(corresponding to the pre-1.0 default) and
- It is now possible to implement custom citation styles.
@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:
@Citep*. See the syntax for citations for details.
- Citations can now include notes, e.g.,
See Ref. [GoerzQ2022; Eq. (1)](@cite).
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
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* 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.