# \[ANN\] DocumenterCitations v1.0.0

**URL:** <https://discourse.julialang.org/t/ann-documentercitations-v1-0-0/101562>\
**Category:** Package Announcements\
**Tags:** announcement, documentation, documenter\
**Created:** [July 13, 2023, 5:10am UTC](https://discourse.julialang.org/t/ann-documentercitations-v1-0-0/101562 "2023-07-13T05:10:07Z")\
**Posts on this page:** 10\
**Page:** 1

<div class="post-metadata">

**Author:** ![goerz](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/goerz/32/3269_2.png) [@goerz](https://discourse.julialang.org/u/goerz)\
**Post date:** [July 13, 2023, 5:10am UTC](https://discourse.julialang.org/t/ann-documentercitations-v1-0-0/101562/1 "2023-07-13T05:10:07Z")

</div>

[DocumenterCitations.jl](https://github.com/JuliaDocs/DocumenterCitations.jl) is a [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl) plugin to add BibTeX citations to your documentation.

By default, [DocumenterCitations.jl](https://github.com/JuliaDocs/DocumenterCitations.jl#readme) 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]](#screenshot).”

 ![Rendered bibliography of two references, [1] and [2]](https://global.discourse-cdn.com/julialang/original/3X/b/7/b764ed00c0eaa6b3125a0ac53a786d9dd8a8def5.png)

Alternatively, [author-year](https://juliadocs.org/DocumenterCitations.jl/dev/gallery/#author_year_style) and [alphabetic](https://juliadocs.org/DocumenterCitations.jl/dev/gallery/#alphabetic_style) citations styles are available. It is also possible to define [custom styles](https://juliadocs.org/DocumenterCitations.jl/dev/gallery/#custom_styles).

The project recently became part of the [JuliaDocs organization](https://github.com/JuliaDocs) and is now available in its first “stable” version [1.0](https://github.com/JuliaDocs/DocumenterCitations.jl/releases/v1.0.0).

## Usage

- Place a BibTeX [`refs.bib`](https://github.com/JuliaDocs/DocumenterCitations.jl/blob/master/docs/src/refs.bib) file in the `docs/src` folder of your project. Then, in [`docs/make.jl`](https://github.com/JuliaDocs/DocumenterCitations.jl/blob/master/docs/make.jl), instantiate the `CitationBibliography` plugin and pass it to [`makedocs`](https://documenter.juliadocs.org/stable/lib/public/#Documenter.makedocs):

- Optional, but recommended: [add CSS to properly format the bibliography](https://juliadocs.github.io/DocumenterCitations.jl/dev/styling/)

- Somewhere in your documentation, include a markdown block

- Anywhere in the documentation or in docstrings, insert citations as, e.g., `[GoerzQ2022](@cite)`, which will be rendered as “[[2]](#screenshot)” and link to the full reference in the bibliography.

See the [documentation](https://juliadocs.github.io/DocumenterCitations.jl) and especially the [Syntax section](https://juliadocs.org/DocumenterCitations.jl/dev/syntax/) for details.

## New Features

From the [release notes](https://github.com/JuliaDocs/DocumenterCitations.jl/blob/master/NEWS.md) for the 1.0 release:

- `CitationBibliography` now takes a `style` keyword argument. The default style is `style=:numeric`. Other built-in styles are `style=:authoryear` (corresponding to the pre-1.0 default) and `style=:alpha`.
- It is now possible to implement [custom citation styles](https://juliadocs.org/DocumenterCitations.jl/dev/gallery/#custom_styles).
- The `@bibligraphy` block can now have additional options to customize which references are included, see [Syntax for the Bibliography Block](https://juliadocs.org/DocumenterCitations.jl/dev/syntax/#Syntax-for-the-Bibliography-Block).
- It is possible to generate [secondary bibliographies](https://juliadocs.org/DocumenterCitations.jl/dev/syntax/#noncanonical), e.g., for a specific page.
- There is [new syntax](https://juliadocs.org/DocumenterCitations.jl/dev/syntax/#Syntax-for-Citations) to create links to bibliographic references with arbitrary text.
- The following variations of the `@cite` command are now supported: `@citet`, `@citep`, `@cite*`, `@citet*`, `@citep*`, `@Citet`, `@Citep`, `@Cite*`, `@Citet*`, `@Citep*`. See the [syntax for citations](https://juliadocs.org/DocumenterCitations.jl/dev/syntax/#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](https://github.com/ali-ramadhan/DocumenterCitations.jl/releases/tag/v0.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:

```julia
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](https://juliadocs.org/DocumenterCitations.jl/stable/syntax/#Citations-in-docstrings).

If you are using `DocumenterCitations` in your project, consider opening a pull request to add a link to the [list of examples](https://juliadocs.org/DocumenterCitations.jl/dev/#Examples).

For any feature requests, please don’t hesitate to [open an issue](https://github.com/JuliaDocs/DocumenterCitations.jl/issues).

---

<div class="post-metadata">

**Author:** ![kellertuer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kellertuer/32/220707_2.png) [@kellertuer](https://discourse.julialang.org/u/kellertuer)\
**Post date:** [July 13, 2023, 6:56am UTC](https://discourse.julialang.org/t/ann-documentercitations-v1-0-0/101562/2 "2023-07-13T06:56:27Z")

</div>

Woah! This looks amazing! Thanks for all the work!

I checked back on this every now and then before it moved into the JuliaDocs org and was usually missing one or two things, e.g. bibliography per page and the possibility of `'citet` – but all that is present now! I am very much looking forward to reworking all my references (I use them a lot in my docs) to unify them and being read from a bibtex file.

---

<div class="post-metadata">

**Author:** ![tecosaur](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tecosaur/32/23206_2.png) [@tecosaur](https://discourse.julialang.org/u/tecosaur)\
**Post date:** [July 13, 2023, 8:48am UTC](https://discourse.julialang.org/t/ann-documentercitations-v1-0-0/101562/3 "2023-07-13T08:48:30Z")

</div>

This looks cool! It would be good if CSL were used for the citation styles though, but unfortunately as far as I’m aware CSL.jl doesn’t yet exist.

---

<div class="post-metadata">

**Author:** ![kellertuer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kellertuer/32/220707_2.png) [@kellertuer](https://discourse.julialang.org/u/kellertuer)\
**Post date:** [July 13, 2023, 8:59am UTC](https://discourse.julialang.org/t/ann-documentercitations-v1-0-0/101562/4 "2023-07-13T08:59:30Z")

</div>

I was even thinking about starting CSL.jl myself but until now I am too busy already with my existing projects; but I would surely help if someone started that.

---

<div class="post-metadata">

**Author:** ![goerz](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/goerz/32/3269_2.png) [@goerz](https://discourse.julialang.org/u/goerz)\
**Post date:** [July 13, 2023, 9:32am UTC](https://discourse.julialang.org/t/ann-documentercitations-v1-0-0/101562/5 "2023-07-13T09:32:31Z")

</div>

CSL would definitely be welcome. There’s an issue with some notes for that: [Support for arbitrary CSL styles · Issue #13 · JuliaDocs/DocumenterCitations.jl · GitHub](https://github.com/JuliaDocs/DocumenterCitations.jl/issues/13)

---

<div class="post-metadata">

**Author:** ![Craig\_Hamel](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/craig_hamel/32/202434_2.png) [@Craig\_Hamel](https://discourse.julialang.org/u/Craig_Hamel)\
**Post date:** [July 13, 2023, 9:26pm UTC](https://discourse.julialang.org/t/ann-documentercitations-v1-0-0/101562/6 "2023-07-13T21:26:34Z")

</div>

Is there a way to include all references in a bib but ignore a few supplied as a list?

---

<div class="post-metadata">

**Author:** ![goerz](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/goerz/32/3269_2.png) [@goerz](https://discourse.julialang.org/u/goerz)\
**Post date:** [July 13, 2023, 11:19pm UTC](https://discourse.julialang.org/t/ann-documentercitations-v1-0-0/101562/7 "2023-07-13T23:19:20Z")

</div>

There is not, but it probably wouldn’t be very hard to implement. You could basically have the same syntax as for [explicit inclusion](https://juliadocs.org/DocumenterCitations.jl/stable/syntax/#Explicit-references), but with a minus sign in front of the keys to indicate explicit exclusion (hopefully, nobody starts their citation keys with minus).

It feels a little far-fetched, though… why not just leave the entries you don’t want to show out of the `.bib` file? Can you elaborate a little on your use case?

---

<div class="post-metadata">

**Author:** ![goerz](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/goerz/32/3269_2.png) [@goerz](https://discourse.julialang.org/u/goerz)\
**Post date:** [July 14, 2023, 8:16pm UTC](https://discourse.julialang.org/t/ann-documentercitations-v1-0-0/101562/8 "2023-07-14T20:16:30Z")

</div>

Opened an issue at [Allow to exclude specific entries from the bibliography · Issue #23 · JuliaDocs/DocumenterCitations.jl · GitHub](https://github.com/JuliaDocs/DocumenterCitations.jl/issues/23)

> with a minus sign in front of the keys to indicate explicit exclusion

Keys can technically start with a minus, so maybe that’s not the ideal syntax. Nor is putting a space after the minus, because that looks like a markdown list. Using `! ` (with a space) would work, though.

I’d still be interested in understanding the use case for this a little better.

---

<div class="post-metadata">

**Author:** ![Craig\_Hamel](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/craig_hamel/32/202434_2.png) [@Craig\_Hamel](https://discourse.julialang.org/u/Craig_Hamel)\
**Post date:** [July 15, 2023, 2:46am UTC](https://discourse.julialang.org/t/ann-documentercitations-v1-0-0/101562/9 "2023-07-15T02:46:26Z")

</div>

I was thinking of a real lazy way to make a CV from exporting citations from google scholar but removing some things like repeat citations from preprints, conference abstracts, and other oddities that show uo from time to time.

---

<div class="post-metadata">

**Author:** ![goerz](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/goerz/32/3269_2.png) [@goerz](https://discourse.julialang.org/u/goerz)\
**Post date:** [July 15, 2023, 7:37pm UTC](https://discourse.julialang.org/t/ann-documentercitations-v1-0-0/101562/10 "2023-07-15T19:37:05Z")

</div>

Quite honestly, I’m skeptical that you’ll have much luck with that. Any BibTeX code you get off Google Scholar is probably going to be too low quality (missing / extra / inconsistent / improperly capitalized fields, no DOI, etc.) to be very useful. If you have conference contributions or seminar talks, those likely won’t even show up on Google Scholar. You’ll be much better off maintaining a clean `.bib` file by hand for your CV website. That’s [what](https://github.com/goerz/michaelgoerz.net/blob/master/content/research/papers.bib) [I](https://github.com/goerz/michaelgoerz.net/blob/master/content/research/conferences.bib) [do](https://github.com/goerz/michaelgoerz.net/blob/master/content/research/seminars.bib) for [my own website](https://michaelgoerz.net), albeit [rendered via a Python script](https://github.com/goerz/michaelgoerz.net/blob/master/src/bibliography.py).

Also note that there’s some [potential issues](https://github.com/JuliaDocs/DocumenterCitations.jl/issues/15#issuecomment-1634636228) with `DocumenterCitations` and arbitrary BibTeX files: Not everything that works in a LaTeX context is going to work perfectly with `DocumenterCitations`, simply because the strings in the `.bib` file aren’t going be run through the TeX engine, but are considered plain text or markdown after some basic cleanup.