Markdown Citation Renderer: pandoc style citations => proper references

[rufuspollock]

Want something like this in markdown:

Blah blah [@doe99; @smith2000; @smith2004].

To become this:

Blah blah (Doe 1999, Smith 2000, 2004).

Or, a fuller version like:

John Doe, "Frogs," *Journal of Amphibians* 44 (1999);
Susan Smith, "Flies," *Journal of Insects* (2000);
Susan Smith, "Bees," *Journal of Insects* (2004).

See pandoc for more: https://pandoc.org/MANUAL.html#extension-citations

🎁 Bonus: generating a reference section at the end of a document ie. list of citations. This could be something that is explicitly inserted by having a special item like [references] just like one has [toc] or maybe more MDX style <ReferencesList />

Acceptance

• [ ] Clear description of what we want
• [ ] Documented manual approach to doing this (i.e. manually add references to docs using obsidian)
• [ ] Remark or similar plugin to do what we want
• [ ] Document in editor guide

Tasks

• [ ] Document our current flow for semi-manual addition of references @smdiehl
• [ ] Analyse what is needed for this to work e.g. do we need a bibtex file exported locally (or can we connect to zotero as part of the build or ...)
• [ ] Create

Notes

• What is the format of the citations? ✅ Pandoc style i.e. https://pandoc.org/MANUAL.html#extension-citations Blah blah [@doe99; @smith2000; @smith2004].
• What result do we expect in html? Do we need to be customizable via https://citationstyles.org? ✅ something like Doe (1999) for short and TODO style for full. Don't need customizability and can just default to one style
• How does this work? Does it need a bibtex/json file? 🚧 assume it does - see architecture diagram below. But not certain
• Does a remark plugin already exist for this? ✅ Found 2. First seems more recent and more appropriate on quick scan. However, it just produces syntax tree and does not render the citations. https://github.com/benrbray/remark-cite & https://github.com/Symbitic/remark-plugins/tree/master. May need more research here.
• What is the obsidian plugin? ✅ https://github.com/hans/obsidian-citation-plugin - uses pandoc style citations

Architecture

graph LR

a[Markdown file w/ citation]
b[Bibliography file with citation keys]
b2[Citation Style info]
c[Processor]
d[Output rendered file with proper citation]

a --> c
b --> c
b2 -.optional.-> c

c --> d

[rufuspollock]

@sdiehl any info you can share on your current setup for adding references e.g. do you have a local bib file you export to or how does it work with the obsidian plugin

(Aside: shall we start documenting this kind of stuff e.g. obsidian plugin setup and config for ourselves and other potential editors in the meta section e.g.meta/obsidian?)

[sdiehl]

I'm doing this manually at the moment. It requires a lot of work and probably doesn't scale very well unless others have a huge mental map of all the literature. But if we have an automated process it's easy to reverse what I've done into something automatic.

[AceTheCreator]

@rufuspollock @sdiehl is this issue been assigned to anyone yet?

[rufuspollock]

@AceTheCreator it hasn't and you could have a go at it.

[SalBayat]

I have been reviewing this issue, and my assumptions in terms of workflow are as follows:

The ultimate goal is to write something in a markdown file, as you are writing, you can insert a citation, these citations are then used either to automatically generate a bibliography/endnotes, or run the file through a script that then produces the endnotes which you can add to the file. Is this the desired outcome?

I use LibreOffice and the Zotero plugin allows me to insert a citation, choose the citation from Zotero, and then generates the Bibliography/Endnotes automatically. I can change the citation style at any point, and the formatting changes are completed automatically. You are no doubt already familiar with this functionality.

I am not familiar with Obsidian, is that what the majority of people are using for editing markdown files?

For example, I use Atom, and am currently looking at two plugins that could help me create a similar workflow to the one I use in LibreOffice:

https://github.com/oztalha/zotero-picker https://atom.io/packages/zotero-citations

Before I proceed further, is there a hard requirement to use Obsidian for this workflow?

As an aside, superscript numbers for citations make a text far more readable. For technical and academic journals, citing the author/year makes sense as the audience is familiar with the literature and subject, however, given the nature of this project and its target audience, it may be worth prioritizing readability over formality.

[rufuspollock]

@SalBayat sorry for slow reply - have not had a chance to review properly. Please feel free to dive in other issues - and saw the proofing PR which are themselves very useful.