Warning on 2021-06-21: Don’t try this work-around

With a pandoc 2.5 installation on Ubuntu 20.04.2 LTS I am not able to get this hack working anymore.

My suggestion is to look into some of the better solutions that were later implemented in ox-hugo.

Introduction

I have written before explaining how you can use org-ref to insert citations into your org mode documents, and then have them export perfectly into PDF documents via LaTeX.

On my quest for personal knowledge management nirvana where my org mode files serve as the single universal source of truth, from which I can generate any other document and publication formats that might be required, I ran into the problem of org-ref citations on the one hand, and ox-hugo’s use of pandoc-style citations on the other.

I could not make peace with the fact that I would have to use different styles of citations in org mode, depending on what my intended output modality was going to be.

What exactly is the issue?

org-ref expects citations of the form cite:surname2011 or cite:surname2011,otherref2012. Depending on the bibliography configuration, citep: and cite: can result in different output, e.g. parenthetical or inline.

ox-hugo first converts org mode to blackfriday-flavour markdown, and then, if if the relevant metadata is found, passes that markdown through pandoc and pandoc-citeproc to have pandoc-style [@surname2011;otherref2012] citations resolved.

If you intended to generate PDF, you would have to use style 1, whereas if you were intending to publish on your website using ox-hugo, you would have to switch all of your citations.

Surely there must be a way to solve this!

Until someone comes up with an actual solution, you can make the following change to the org-ref-make-format-function macro in org-ref-core.el.

In short, copy the cond sexp handling pandoc export and use it to override the existing markdown export case by simply inserting it before it.

What will happen, is that during the first org to markdown conversion, org-ref-style citations will be converted to pandoc-style citations.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

;; copy 'pandoc sexp here, and change to 'md -------------------------
((eq format 'md)
 (cond
  (desc ;; pre and or post text
   (let* ((text (split-string desc "::"))
          (pre (car text))
          (post (cadr text)))
     (concat
      (format "[@%s," keyword)
      (when pre (format " %s" pre))
      (when post (format ", %s" post))
      "]")))
  (t
   (format "[%s]"
           (mapconcat
            (lambda (key) (concat "@" key))
            (org-ref-split-and-strip-string keyword)
            "; ")))))
;; end of copied 'pandoc sexp ----------------------------------------
((eq format 'md)
 (mapconcat (lambda (key)
              ;; this is an html link that has an anchor to jump back to,
              ;; and links to the entry in the bibliography. Also contains
              ;; a tooltip.
              (format "<sup id=\"%s\"><a href=\"#%s\" title=\"%s\">%s</a></sup>"

It would probably be better to write some sort of opt-in bridge code that could for example advise the generated org-ref export functions to perform the hack above in a nicer way.

Other solutions to this problem have been discussed on the ox-hugo github, but it looks like they are letting org-ref do all the work, while here we are simply converting org-ref-style citations to pandoc-style before the ox-hugo pandoc stage.

Can you show me how this works?

Sure!

This org source:

1
2
3
4
5

I recently read a really great paper on neural speech synthesis using
transfer learning via a speaker discrimination task
cite:jiaTransferLearningSpeaker2018. If you would like to reproduce that work,
you'll probably run into the VoxCeleb2 dataset
cite:chungVoxCeleb2DeepSpeaker2018.

Will be rendered like this:

I recently read a really great paper on neural speech synthesis using transfer learning via a speaker discrimination task jiaTransferLearningSpeaker2018. If you would like to reproduce that work, you’ll probably run into the VoxCeleb2 dataset chungVoxCeleb2DeepSpeaker2018.

Note 1: Limitations

With this hack, there’s no easy way to produce inline citations, e.g. [-@cite1] or @cite1. One would have to modify the patched code to distinguish between citep: and cite: in the pandoc-translation.

Note 2: org-ref-default-bibliography

For org-ref’s super slick interactive citation insertion function (C-c ]) to work, you have to set the file-local org-ref-default-bibliography to the path of the .bib file.

I have the following at the end of this org file to make that happen:

1
2
3

# Local Variables:
# org-ref-default-bibliography: "./org-ref-ox-hugo-citations.bib"
# End:

Conclusion

This post shows one hacky way of continuing to use only org-ref-style cite: links in your org files, but still having the ability of producing ox-hugo pages with perfect bibliographies.

As an aside, after years of org2blog and more recently simply editing hugo markdown directly, this is my first ever post produced from org mode with ox-hugo!