Make it easier to cite references

[gcushen]

Currently, footnotes can be used for citing references, but this requires manually pasting in each reference from your ref. manager as a footnote.

Therefore, let's consider adding a more automated referencing approach that can read refs direct from a file.

Investigation into Hugo's Mmark citation system:

1. Investigate if Hugo supports the necessary version of Mmark and correct implementation for cites to work
   • tested with Hugo 0.55.6 and Mmark citations are broken in the Hugo implementation - refs must be formatted as XML within a <div> and Hugo generates an empty citation tag and shows the ref fields as unformatted verbatim at end of page. Also, see similar result experience by another user: https://discourse.gohugo.io/t/citations-using-mmark/16723
   • therefore, this option is ruled out as a solution

Solution

1. User exports references for a blog post as JSON from their reference manager, such as Zotero or Mendeley, saving the file as references.json within a post's folder
2. Add Citeproc JS to parse and render the JSON references
   • Fallback solution: introduce a new shortcode for citing and a page logic to render reference section

Decisions

1. Should a JSON file be exported for each post, or should we have a single large JSON file for the entire site?
   • Decision: take a references.json within a post's folder as the input

[HughP]

@gcushen In the opening issue you mention BibTeX references. BibTeX (as I presume you know) is a data format. If this issue is exclusive to processing using that data format then I apologize as my feedback/discussion takes a more data format agnostic approach to the issue (and I hope that others feel free to improve on my feedback). While discussing Bibliographic citations I am also going to discuss Footnotes as I think these are a very similar use case.

We are happy and grateful that Academic supports endnotes on pages (including blog posts) with the [^1] syntax. And then at the end of the page one is opportune to put in the rest of the note following the syntax [^1]:. This has two unfortunate drawbacks: 1) no automatic numbering. 2) the content of the note is not kept in flow with the placement of the note. These are both pain points to authors.

The following syntax would have a better flow: {{< footnote text="something important to say." >}} Where the footnote is then automatically numbered and then the second element (I think this is called a param. But whatever it is, is then added to the footnote section of the template.

I am at a loss on how to get hugo to count the total number of footnotes when it renders the shortcodes. If there were a way to count all the footnotes on a page and then assign each a number at render time this would solve the footnote challenge. I wonder if the page format/template could have a function which would len() the number of {{<footnote >}} elements and then somehow assign each one a progressive number starting with 1 (or style it if need be * § † ‡).

I am curious, though Has anyone experimented with a way to also add citations in a references section on the post? Note that this is different from the publications section of Academic's features. My quick thought is that citations and footnotes could be solved with the same pattern.

With citations there are generally two parts to a citation the inline portion (Robins 2018) and the portion which would get added to the references section of a paper Robins, Jerod. 2018. Sparkles in the sky. Journal of fictitious literature. 27(2): 12-25. DOI: 10.1234/568910

I would imagine that a short code could be constructed in the following manner {{<citation inline="Robins 2018" reference="Robins, Jerod. 2018. Sparkles in the sky. Journal of fictitious literature. 27(2): 12-25. DOI: 10.1234/568910" >}} where there are two params the first for inline citation and the second to be added to the references section of the page/post.

With a short code I can clearly see how to add either of these params in one of the two places. But how does one create a short code which adds content in two places (and alphabetical order in the second place?

Tools like citation.js take the data format from BibTeX and convert it to CSL-Json. which can then be styled dynamically with CSL profiles (also take a look at citeproc-js). So, if someone wants to use APA in their posts but someone else wants to use MLA they could (ideally) set a param in their theme for citation style for citations in the site params.toml or on the page if an override of the cite default is needed. Using CSL would greatly increase the flexibility of the citation styles available, while also greatly decreasing the work needed to maintain this feature.

One drawback I can see is that when citation data is maintained in its own file it then needs to be referenced — usually with a key. This means we might have a shortcode with the shape of something like: {{<citation refkey='" >}} or {{<citation r12345 >}} where the param is the refkey. This has the disadvantage that the actual citation data is not in the same file which is using the citation.

But if we abstract the json citation data to its own json file and attach that to a page or post as a resource, is that ok? we do this with photos. There is the Hugo data folder but it seems pertinent to keep the citations of a post or page with the post or page, especially when considering portability.

Does hugo have the ability to create files on the fly? It seems to me that output-formats can do this. If they can, the contents of footnotes and citations short codes could be appended to one of these output formats (which is itself a partial) as Hugo parses the page at render time, then a reference and footnote section at the end could pull in the content of the dynamically generated partial to the HTML page at the end of the render of each page.

Here are a few citations to play around with. I exported these from Zotero as CSL-JSON.json and Bibtex.bib. I had to rename the files with the .txt extension to get them to upload to github.
bibtex.txt
CSL-JSON.txt

[gcushen]

This issue is regarding making it easier to cite in general. The "Bibtex" in the title was just an example and no longer relevant so I'll remove it.

I began investigating this soon after the issue was created and it was decided that any solution would use the web-friendly JSON reference standard, as you mentioned :)

Note that this issue is somewhat related to #1020 on generating Publication pages directly in Hugo, without Academic Admin.

[gcushen]

One of the next decisions that need to make is should a JSON file be exported for each post, or should we have a single large JSON file for the entire site? Each approach has pros and cons which need to be considered.

[vkehayas]

Not sure if it is practical for academic but with RMarkdown we specify a bib file in the header and use something like [@smith_refFirstWord_2019] in the text. At render time, pandoc is called, with the help of a library called citeproc, that renders the citations and then converts the document to a pre-specified format.

…

On Fri, 19 Jul 2019, 00:14 George, ***@***.***> wrote: This issue is regarding making it easier to cite in general. The "Bibtex" in the title was just an example and no longer relevant so I'll remove it. I began investigating this soon after the issue was created and it was decided that any solution would use the web-friendly JSON reference standard, as you mentioned :) Note that this issue is somewhat related to #1020 <#1020> on generating Publication pages directly in Hugo, without Academic Admin. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#830>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAJGGH7R5E2HZD4FIPYNY3DQADMMXANCNFSM4GIDUR6A> .

[HughP]

With @vkehayas solution type the file specified could be either a master (per site) file or a per page file.

[AustenLamacraft]

A file of references for each post seems very natural to me. What’s the upside of a master file? There is this notion of a researcher maintaining a master file of useful references but I’ve never found that to work. References are defined by the document citing them so should live with that document.

Happy to try something like the citeproc.js solution.

[gcushen]

Hugo are yet to introduce such functionality. However, Wowchemy Version 5 Beta 0 introduced a Cite shortcode which may help address some of these use cases - interested to hear feedback :)

First, create a page for the publication that you wish to reference if one doesn't already exist and then cite it using the shortcode:

{{< cite page="/publication/preprint" view="4" >}}

where view="4" is the citation view.

The Hugo Academic CLI tool can be used to automatically generate publication pages from Bibtex, which can then be cited.

Additionally, footnotes can still be used for citing external references, albeit requires manually pasting in each reference from your ref. manager as a Markdown footnote.

[gcushen]

Closing as no further feedback on the two current approaches for citations in my previous comment and also this issue is now tracked in the Hugo repo at gohugoio/hugo#6101 - feel free to add a 👍🏻 there to upvote.

[fretchen]

I must admit that the single bibtex for each post file would be really cool as this also the approach taken by the jupyter book project.

And adding every citation that I would like to have in some blog post to my own citation folder does not seem super simple either.

Would be awesome if the cite short-cut could be extended to work with bibtex...

[HughP]

@fretchen You might be interested in this hugo module. It uses CSL JSON but is really powerful https://github.com/loup-brun/hugo-cite

[fretchen]

@fretchen You might be interested in this hugo module. It uses CSL JSON but is really powerful https://github.com/loup-brun/hugo-cite

@HughP this worked out quite nicely. Thanks a lo. For reference of other users, here were the steps that I had take to make it work:

• Add the hugo-cite module to the [[module]] section in config/_default/config.toml . It has to be in front of the wochemy modules:

[module]
  [[module.imports]]
    path = "github.com/loup-brun/hugo-cite"
  [[module.imports]]
    path = "github.com/wowchemy/wowchemy-hugo-modules/wowchemy"
  [[module.imports]]
    path = "github.com/wowchemy/wowchemy-hugo-modules/netlify-cms-academic"

• Run hugo mod get -u
• Add the file layouts/partials/custom_head.html with the content

<link rel="stylesheet" type="text/css" href="{{ "/hugo-cite.css" | relURL }}" />

• Add a bib.json file in the folder of choice with the test content:

[
    {
        "id": "Lessig 2002",
        "author": [
            {
                "family": "Lessig",
                "given": "Lawrence"
            }
        ]
    }
]

• Cite it in the markdown file:

---
# Files in this folder represent a Widget Page
type: blank
headless: true
title: "Test a Citation"
weight: 80
bibFile: content/research/bib.json
active: false
---

 And here is the citation of {{< cite "Lessig 2002" >}}. Let me continue with the text and see what happens.