Add support for citation syntax

[zawlin]

https://github.com/hackmdio/codimd/issues/419

I was trying to use codimd as a research tool and citation has quickly become a major problem.

You can see an example of how I was using in the following link.

https://demo.codimd.org/D-dCnDMvRAOs-iDBIE1ABA

The following features should be available:

• Automatic completion of citation, using either citation id or text based search using title.
• Automatic id generation for new entries. Now you can see that I am using a hacky way, and need to manually keep track of next available id.
• Would also be nice to remove the html anchor as it makes reading difficult.
• Ability to go back to previous position after jumping to the anchor. Now you can see that when I click on the internal anchor link and I use browser back button, it does not work as my previous reading position has no anchors. I am not exactly sure how it can be fixed but it disrupts the reading experience. One idea would be to have a small javascript embedded in the anchor link, which will remember the current position and jump back to it later.
• Ability to export all citations in bibtex compatible format, to facilitate writing in final latex document
• Even better would be to just export directly to latex

[frederik-elwert]

I second this. Having citations would allow scholars to use CodiMD as a real alternative to Google Docs and the like for collaborative writing.

Since CodiMD’s markdown is already largely compatible with pandoc’s, I would suggest to implement the citation syntax from pandoc.

To prevent relying on an external bibtex file or so for the bibliographic information, one could use embedded references in the YAML metadata, which pandoc also supports.

citeproc-js is a JavaScript citation processor that probably could be leveraged to do the actual heavy lifting (instead of pandoc’s Haskell implementation).

[boutil]

This software has been made available to a federation of math departments of French universities. It would be great to have this kind of functionality as it is the first question I got when I announced to people in my department. This is really a functionality that is sought by researchers.

[frederik-elwert]

FWIW, the Zettlr project created the Citr library that implements pandoc’s citation parsing algorithm in JavaScript.

[SISheogorath]

So I looked a bit into Citr and I'm not really sure about how this library would look like once integrated with CodiMD. The syntax looks bad for markdown to me, since it basically uses markdown link notation which already has a function in our markdown parser.

So I wonder what would be the goal. Having the sources in an exportable json format? Linking the sources in the markdown text? Adding the sources at the end of the document?

It would be nice when one could give some insight into what the expected result would look like.

Please note, I saw the initial document, but actually struggle to understand what it tries to tell me. I.e. What is something that should be written by the user and what should be integrated.

[frederik-elwert]

@SISheogorath I don’t know if we all have the same thing in mind.

From my perspective, the most natural solution would be to implement citations just as pandoc does. Pandoc is already heavily used in academic workflows, and this way CodiMD could be used as a collaborative editor for scholarly articles.

You can find the supported syntax in the pandoc manual. In it’s base form, it also utilizes square brackets, as in

Blah blah [see @doe99, pp. 33-35; also @smith04, chap. 1].

Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].

Blah blah [@smith04; @doe99].

But it also allows for special forms like in-text citations:

@smith04 says blah.

@smith04 [p. 33] says blah.

Here’s the workflow that I personally would think of:

1. Upload a bibliographic database, e.g. in BibTeX or CSL JSON format.
2. Specify a citation style, e.g. as a link to a CSL style. If not specified, use a reasonable default (Chicago author-date is what pandoc uses).
3. Reference literature in the text using the @key syntax. CodiMD could provide auto-completion, potentially with a preview of the entry
4. In the rendered document, CodiMD should replace in-text citations with formatted references, and add a bibliography at the end of the document, if the style requires one.

Since citation processing is a rather huge task, I would imagine that using existing libraries would help. citeproc-js is the de-facto standard implementation of CSL. It could act as the work-horse, getting citations from CodiMD (as JSON structures) and returning formatted references and bibliography. The Markdown parser would need to support the citation syntax and create JSON structures for each MD reference, so that it can pass these to citeproc-js. Citr does this, but if it does not play well with CodiMDs parsing infrastructure, references could also be implemented in the parser itself.

So a Markdown document could look like this:

---
bibliography: "https://my.pad.org/uploads/upload_123456789abcdef.bib"
csl: "https://www.zotero.org/styles/apa"
---

Blah blah [see @doe99, pp. 33-35; also @smith04, chap. 1].

# References

In the rendered version, this would look roughly like:

Blah blah (see Doe 1999, 33–35; also Smith 2004, chapter 1).

References

Doe, John (1999). A book. Chicago University Press.

Smith, Adam (2004). Another book. Brill.

[jiboncom]

MyST Markdown (https://mystmd.org) has support for citations, onmouseover information and a javascript renderer. It is great for academic work!

[thomjur]

Hi!

This feature would be highly significant for us as we are working on integrating HedgeDoc into our collaborative academic publishing workflow, ideally following the description by @frederik-elwert. I noticed that this feature is currently listed as part of Milestone 2.x. Does this indicate that someone is actively developing this feature already or has plans to do so in the foreseeable future? I don't mean to rush you, but we are in the process of determining which tools to incorporate into our publishing workflow. HedgeDoc is a crucial candidate for us, especially if it will have some form of citation feature. Thank you!

[mrdrogdrog]

@thomjur

Milestone 2.x contains all the issues we will work on after the release of 2.0