# Citations in docs

**URL:** <https://discourse.julialang.org/t/citations-in-docs/5066>\
**Category:** General Usage\
**Created:** [July 25, 2017, 7:46pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066 "2017-07-25T19:46:50Z")\
**Posts on this page:** 20\
**Page:** 2

<div class="post-metadata">

**Author:** ![mortenpi](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mortenpi/32/158_2.png) [@mortenpi](https://discourse.julialang.org/u/mortenpi)\
**Post date:** [July 31, 2017, 3:20pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/21 "2017-07-31T15:20:56Z")

</div>

I can’t really say how this should be implemented because I am not really that familiar with the code of DocStringExtensions. But as far as I know, you can basically register callbacks to Julia’s docsystem. You’d have to read DocStringExtensions code to figure out how all that works.

From the design point of view, DocStringExtensions relies on the dollar-sign interpolation. So it could look something like this:

```julia
using DocStringExtensions
import DocStringExtensions: Citations

# Adding citations in source
Citations.add_reference(:fisher,
    title="...",
    author="...",
    year=1999
)

# .. or importing from a bibtex file
Citations.bibtex("references.bib") # relative to @ __FILE__

"""
This sentence has a citation $(CITE fisher).

$(REFERENCES)
"""
function foo end

```

And the docstring should be expanded to the following Markdown:

```markdown
This sentence has a citation [Fisher 1999].

# References

* Fisher, A. (1999) Title. Etc. [doi:xyz](https://dx.doi.org/xyz)

```

`$(REFERENCES)` would gather up all the `$(CITE)`s in a docstring. I don’t have a preference on the exact citation format and it should be easy to support different styles (`Citations.setstyle()` or something like that, with a reasonable default).

Not sure how one should handle modules / packages exactly. The reference database should probably be shared within a package, but packages should not pollute each other’s databases. But from a technical side I’m not sure how easy it is to figure out what package a particular docstring lives in.

Since this would make DocStringExtensions depend on the BibTex parser, it might be better to have this in a separate package, one which would depend on DocStringExtensions and the parser (DocStringCitations?). DocStringExtensions could contain all the code to facilitate the development of these types of extensions.

---

<div class="post-metadata">

**Author:** ![jacobcvt12](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jacobcvt12/32/2695_2.png) [@jacobcvt12](https://discourse.julialang.org/u/jacobcvt12)\
**Post date:** [July 31, 2017, 5:59pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/22 "2017-07-31T17:59:04Z")

</div>

Thanks @mortenpi.

Does anyone want to take a stab at this? If not, I’m happy to work on it (as time permits).

---

<div class="post-metadata">

**Author:** ![stevengj](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/stevengj/32/71_2.png) [@stevengj](https://discourse.julialang.org/u/stevengj)\
**Post date:** [July 31, 2017, 6:15pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/23 "2017-07-31T18:15:34Z")

</div>

> [@jacobcvt12](#):
>
> @mortenpi, now that @bramtayl has a working bibtex parser, what should the process be for splicing references into docstrings?

I would say that the next step, before we worry about integration with docstrings, would be a working citation formatter: [https://github.com/bramtayl/BibTeX.jl/issues/3](https://github.com/bramtayl/BibTeX.jl/issues/3)

---

<div class="post-metadata">

**Author:** ![jacobcvt12](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jacobcvt12/32/2695_2.png) [@jacobcvt12](https://discourse.julialang.org/u/jacobcvt12)\
**Post date:** [July 31, 2017, 6:51pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/24 "2017-07-31T18:51:59Z")

</div>

Good call. Thanks for pointing out.

---

<div class="post-metadata">

**Author:** ![Azzaare](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/azzaare/32/21008_2.png) [@Azzaare](https://discourse.julialang.org/u/Azzaare)\
**Post date:** [October 9, 2017, 2:29am UTC](https://discourse.julialang.org/t/citations-in-docs/5066/25 "2017-10-09T02:29:43Z")

</div>

Sorry to bring the topic back (it might be slightly outside of topic …).

I have stupidly decided to create a bibtex parser for a personal project last week without checking if there was something ongoing (I still checked if there was something in the registered repositories though).  
I used Automa.jl to write a parser down in a hundred line. I have never down any parsing before that and I was new to Automa.jl. So it is pretty easy to use.  
It seems to be pretty efficient as soon as we precompile the grammar automata. As most bibliography format are pretty easy grammar it should be easy and quick to produce the automata for other bib format.

For my project, that handles citations networks, I am planning to use a Julia internal type to convert from one format to another. So far it only convert from and to Bibtex. However, there is one interesting feature than maybe would make sense for citations in docs.  
My internal citation format uses a rules system to check the format of a citation. Those rules check the existence (and eventually formatting) of the different fields in bibliography entries. For instance, the basic set of rules when formatting from or to bibtex style check that the relevant fields (required/ optional/ forbidden) are provided (or not).  
Wouldn’t this rule system be good for documentation? As long as the provided entries (as the internal bibliography type) follow the rules needed for the documention, they those entries are converted to the required format for the documention.

I will upload both the bibtexparser and the bibliography internal type and rule system through two packages this week, so I can keep you updated if interested.

---

<div class="post-metadata">

**Author:** ![Azzaare](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/azzaare/32/21008_2.png) [@Azzaare](https://discourse.julialang.org/u/Azzaare)\
**Post date:** [October 10, 2017, 7:24am UTC](https://discourse.julialang.org/t/citations-in-docs/5066/26 "2017-10-10T07:24:20Z")

</div>

OK, after giving it some time, I organized the bibliography packages system as follows:

- A package to handle an internal type for bibliography items in Julia: [BibInternal.jl](https://github.com/Azzaare/BibInternal.jl). It also include the rule system mentioned above (work in progress though).
- Set of parsers from any citation language to the BibInternal.jl format. Currently compatible with BibInternal.jl is only [BibTeXParser.jl](https://github.com/Azzaare/BibTeXParser.jl). If other parsers are or become available it should be pretty straightforward to make them compatible with BibInternal.jl.
- A top package to aggregate BibInternal.jl and any parser: [Bibliography.jl](https://github.com/Azzaare/Bibliography.jl). Importing from (parsing) and exporting to (file or string) BibTeX is less than 40 lines, thanks to multiple dispatch. I think it is pretty straightforward to extend it for the documentation now.

Please note this is just a proposal, and there are a couple of parsers for bibtex or other bibliography languages that are available in Julia (so my parser is not necessarily the best choice).

I will use those package for my own project (unless something better/smoother pops up), so if there is an interest in this organization of packages, I can register (part) of them. Let me know.

---

<div class="post-metadata">

**Author:** ![mkborregaard](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mkborregaard/32/556_2.png) [@mkborregaard](https://discourse.julialang.org/u/mkborregaard)\
**Post date:** [October 10, 2017, 11:09am UTC](https://discourse.julialang.org/t/citations-in-docs/5066/27 "2017-10-10T11:09:49Z")

</div>

The discussion here might be relevant for you too: [ANN: Our Julia paper in SIAM Review](https://discourse.julialang.org/t/ann-our-julia-paper-in-siam-review/2886)

---

<div class="post-metadata">

**Author:** ![Azzaare](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/azzaare/32/21008_2.png) [@Azzaare](https://discourse.julialang.org/u/Azzaare)\
**Post date:** [October 12, 2017, 3:26am UTC](https://discourse.julialang.org/t/citations-in-docs/5066/28 "2017-10-12T03:26:28Z")

</div>

> [@mkborregaard](#):
>
> The discussion here might be relevant for you too: ANN: Our Julia paper in SIAM Review

Thank you, that is quite interesting. And a nice application of having a bibliography package system.  
Along with getting all articles related to a package, it would be nice also to generate a citation for the package itself (and maybe related packages) as an online resource. Getting all the contributors, the owner, the url, the current tag version, etc, all formated and then exported to your favourite bibliography format (for instance BibTeX). This could be automated quite easily I suppose.

---

<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 14, 2018, 4:30pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/29 "2018-07-14T16:30:37Z")

</div>

Any news on the BibTeX/References within DocStrings? I would be very happy to use them to cite several of my Algorithms correctly and – best case – to use it also within Documenter.jl for the Documentation in general.

---

<div class="post-metadata">

**Author:** ![chakravala](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/chakravala/32/6832_2.png) [@chakravala](https://discourse.julialang.org/u/chakravala)\
**Post date:** [July 14, 2018, 6:11pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/30 "2018-07-14T18:11:09Z")

</div>

Somewhat tangentially related: I am currently creating a package that will allow people to maintain a database of LaTeX notes, and the Julia package will automatically be able to parse this database of LaTeX notes to extract citations, references, and it will allow authors to generate graph diagrams depicting the inter-relationship and dependencies of definitions, theorems, calculations, references, and results. It might be possible to substitute it in place of a docs system in the future, but for now it’s a prototype concept for maintaining a body of research and citations and making it into a computational graph database.

My hope is to have it fully functional by October, but the prototype is moving along nicely, 0.7+ only.

---

<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 15, 2018, 8:28am UTC](https://discourse.julialang.org/t/citations-in-docs/5066/31 "2018-07-15T08:28:42Z")

</div>

That sounds great! Might be a little too much for my need (I would just like to add literature to thedoumentation of algorithms) – but I am still lookingforward to that package; since it might also help a Documentation (Documenter.jl) to introduce LaTeX commands for nicer writing.

---

<div class="post-metadata">

**Author:** ![bramtayl](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/bramtayl/32/3614_2.png) [@bramtayl](https://discourse.julialang.org/u/bramtayl)\
**Post date:** [July 15, 2018, 2:45pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/32 "2018-07-15T14:45:40Z")

</div>

So after some time trying to port BibTeX parsers, and then some time trying to port Citeproc parsers, I’ve decided to give up. By I still have a thought:

1. put bindings to pandoc into an external package (should already be in Weave.jl I think)
2. Using Requires.jl, add some optional functionality to Documenter based on pandoc

Does that seem reasonable?

---

<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 16, 2018, 5:45am UTC](https://discourse.julialang.org/t/citations-in-docs/5066/33 "2018-07-16T05:45:25Z")

</div>

Citeproc is actually one thing I got quite used to for my homepages (Jekyll and Jekyll-Scholar), which directly works with markdown. I haven’t tried to write something myself (since I am mainly writing my own package on something different), but Weave might be a starting point.

---

<div class="post-metadata">

**Author:** ![tpoisot](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tpoisot/32/19812_2.png) [@tpoisot](https://discourse.julialang.org/u/tpoisot)\
**Post date:** [July 16, 2018, 4:35pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/34 "2018-07-16T16:35:06Z")

</div>

Citeproc is relatively easy to parse if you want something bare-bones, which may be sufficient for in-doc references. References are stored as JSON or YAML, so there wouldn’t be a need to rely on pandoc to generate anything.

---

<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 16, 2018, 4:57pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/35 "2018-07-16T16:57:24Z")

</div>

Thank you for the response. Can you provide a little more detail? For example: How would I get `Documenter.jl` to use such JSON or YAML? How would I invoke citeproc onto the markdown files of Documenter (the `/docs/src`-folder) such that all inline docstrings are also parsed?  
That’s why for now I am looking more for an extension to Documenter – for me, building that from scratch seems to be a never ending story of reading and including quite a few packages and find a way for them to interact.

---

<div class="post-metadata">

**Author:** ![chakravala](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/chakravala/32/6832_2.png) [@chakravala](https://discourse.julialang.org/u/chakravala)\
**Post date:** [August 2, 2018, 3:22pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/36 "2018-08-02T15:22:12Z")

</div>

> [@kellertuer](#):
>
> Thank you for the response. Can you provide a little more detail? For example: How would I get `Documenter.jl` to use such JSON or YAML? How would I invoke citeproc onto the markdown files of Documenter (the `/docs/src` -folder) such that all inline docstrings are also parsed?

My [GitHub - chakravala/VerTeX.jl: Typeset scattered graph data rewriter based on LaTeX nodes](https://github.com/chakravala/VerTeX.jl) package that I announced above uses TOML instead of YAML or JSON by the way. I’ve made some progress on it, and will be considering the citation issue soon, but I’m definitely going to try making a parser for it, and perhaps I will make it a separate package, we’ll see.

---

<div class="post-metadata">

**Author:** ![tpoisot](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tpoisot/32/19812_2.png) [@tpoisot](https://discourse.julialang.org/u/tpoisot)\
**Post date:** [August 3, 2018, 1:30pm UTC](https://discourse.julialang.org/t/citations-in-docs/5066/37 "2018-08-03T13:30:47Z")

</div>

I think yaml and json are reasonable formats because that’s what citeproc uses. You can e.g. export from zotero directly in this format (it’s also supported by pandoc).

---

<div class="post-metadata">

**Author:** ![mpastell](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mpastell/32/350_2.png) [@mpastell](https://discourse.julialang.org/u/mpastell)\
**Post date:** [March 3, 2019, 10:20am UTC](https://discourse.julialang.org/t/citations-in-docs/5066/38 "2019-03-03T10:20:24Z")

</div>

I am adding citation support that doesn’t rely on Pandoc to Weave.jl [Add support for citations by mpastell · Pull Request #185 · JunoLab/Weave.jl · GitHub](https://github.com/mpastell/Weave.jl/pull/185).

I have extended Julia Markdown to parse citations from text and using [Update for Julia 1.x by mpastell · Pull Request #1 · JuliaTeX/BibTeX.jl · GitHub](https://github.com/stevengj/BibTeX.jl/pull/1) to parse bibtex.

The current state is that Latex output works, html works apart from formatting the references. If BibTeXFormat.jl get’s updated then it would be easy to get nice html output as well.

---

<div class="post-metadata">

**Author:** ![cmichelenstrofer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/cmichelenstrofer/32/44392_2.png) [@cmichelenstrofer](https://discourse.julialang.org/u/cmichelenstrofer)\
**Post date:** [November 28, 2022, 1:20am UTC](https://discourse.julialang.org/t/citations-in-docs/5066/39 "2022-11-28T01:20:35Z")

</div>

Has there been any update on this? I don’t see citation information in either `Documenter` or `Markdown`.

---

<div class="post-metadata">

**Author:** ![Krastanov](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/krastanov/32/6817_2.png) [@Krastanov](https://discourse.julialang.org/u/Krastanov)\
**Post date:** [November 28, 2022, 1:38am UTC](https://discourse.julialang.org/t/citations-in-docs/5066/40 "2022-11-28T01:38:41Z")

</div>

Yes, you can use:

> **[GitHub - ali-ramadhan/DocumenterCitations.jl: DocumenterCitations.jl uses...](https://github.com/ali-ramadhan/DocumenterCitations.jl)**
>
> DocumenterCitations.jl uses Bibliography.jl to add support for BibTeX citations and references in documentation pages generated by Documenter.jl. - GitHub - ali-ramadhan/DocumenterCitations.jl: Doc...

[Previous page](https://discourse.julialang.org/t/citations-in-docs/5066.md?page=1)

[Next page](https://discourse.julialang.org/t/citations-in-docs/5066.md?page=3)