Citation Style Language

CSL/citeproc-js deployment

#1

Greetings,

I am using Hugo a static site generator to generate a static HTML based website.

I have a large collection of academic citations in my various Zotero Libraries. I occasionally export my research collections as either topical bibliographies or annotated bibliographies. These surface in my website as “blog posts”. Hugo uses markdown to render its pages (it works well for me).

Hugo also allows me to create data centric content from data stored as JSON stored locally at the time of render, or dynamically after render. I would like to extract data from CSL-JSON.json file and present it in my post according to a predefined CSL file (from the git repo). Of course if I change my site from time to time, when I re-render my static site I might choose to use a different CSL file, and get a different output.

I feel like I am missing a piece of the pipeline here. Is there a browser side javascript library which will put the CSL-JSON data in the proper order per type of item in the Bibliography?

Including javascript on every page with a bibliography is something I am willing to do. (though if the JSON data were rendered in the correct order as defined in the .csl file when Hugo renders the whole site, that would be even better.

I’ve read through the docs on the citeproc-js website, but I’m still missing something if that is the solution.

thanks,

#2

did you look at citations.js as Rintze suggested over at Zotero? That would seem like the thing you’re looking for rather than trying to use citeproc-js client side.

I’m a bit confused by your questions about order in CSL-JSON, though. The order of bibliographies is determined by the citation style and so there is no “right” order in CSL-JSON.

#3

I would not, in general, recommend using client side JS for this. You have the opportunity to run code during page generation — much better to do it then than load a large library and start from scratch on every page load. Unfortunately, Hugo does not have a plugin system, although it appears it may be on a distant roadmap now that the Go language has better support for it.

For any other static site generator that does, or if Hugo eventually gets plugins, my recommendation would be to link to citeproc-rs and run them through that, in a preprocessing plugin. Otherwise, a runner up option is to run it before Hugo, producing a file Hugo can render (like plain HTML). You could write a Makefile to express this dependency relationship. Note that no prebuilt tools exist to do this, as your specific use case is a bit odd, but I could probably hack one together pretty quickly. Last place for a static site would be running a full citeproc in the browser, but it would technically work, no arguing with that.

Re the ordering, there actually is an issue if you do not have a document to build the bibliography from. Many styles sort the bibliography in the order they were cited (the default) or use it as a tiebreaker. A plain CSL-JSON file is a good start, but if you’re trying to link these with a blog post, you’re probably better off using pandoc + pandoc-citeproc to preprocess the posts from Pandoc Markdown [@citations] into HTML with a built in, fully formatted bibliography. This seems much better than manually keeping the post and the the bibliography in sync. On the other hand, if you just want to publish a reading list, then go ahead, but use citeproc with a list of citations in the order they appear. This is what the tool “I could probably hack … together pretty quickly” would do.

(Side note, I originally built citeproc-rs as a pandoc-citeproc replacement, and actually managed to format a document in the early days. But I got funding for Zotero’s use case (RTF and HTML) and haven’t yet rebuilt Pandoc support on the new foundations. This was always going to be difficult, given the plain text vs nested object outputs, but I have kept this in mind so it remains feasible. Supporting this would be ideal for academic blogging in future.)

#4

good point yes; since you’re generating the page statically anyway, using client-side formatting seems to offer few benefits (with significant performance downsides).

And while this is true:

Many styles sort the bibliography in the order they were cited (the default) or use it as a tiebreaker.

it’s also trivially easy to fix with 4 lines added to whichever style you’re using (if it doesn’t sort the bibliography already), so I wouldn’t worry about that too much.

#5

I would suggest using pandoc to generate your bibliographies at page creation time.

#6

Hugo has a pandoc output mode. Can you use that?

#7

Looks like you can! https://gohugo.io/content-management/formats/

#8

The documentation suggest the pan doc output is only for mathjax.

#9

No, that is just saying that it defaults to telling pandoc to format equations using MathJax instead of MathML. You can set any pandoc parameters you want and certainly use any pandoc filter features, like citeproc-pandoc.