Merge pull request #560 from kaushalmodi/org-ref

Add example Org file with org-ref style citations

doc/ox-hugo-manual.org

@@ -2623,6 +2623,43 @@ This property list recognizes these properties:
   find the beginning of the bibliography section.  The default value
   is a regular expression that matches the ~<div
   class="csl-bib-body">~ HTML element exported by ~citeproc.el~.
+*** Org-ref Citations
+:PROPERTIES:
+:EXPORT_FILE_NAME: org-ref-citations
+:END:
+[[https://github.com/jkitchin/org-ref][Org-ref]] citations can be exported to Hugo-compatible markdown/HTML by
+calling ~(org-ref-process-buffer 'html)~ in the
+~org-export-before-parsing-hook~ hook.
+
+Here's an example of how to do that using ~use-package~:
+
+#+begin_src emacs-lisp
+(use-package org-ref
+  :ensure t
+  :init
+  (with-eval-after-load 'ox
+    (add-to-list 'org-export-before-parsing-hook
+                 (lambda (backend)
+                   ;; ox-hugo <- ox-blackfriday <- ox-md <- ox-html
+                   (when (org-export-derived-backend-p backend 'html)
+                     (org-ref-process-buffer 'html))))))
+#+end_src
+
+Minimal example with ~org-ref~ citations:
+
+#+name: code_citation_org_ref
+#+caption: Example of ~org-ref~ citation
+#+begin_src org
+#+title: Citation using ~org-ref~
+
+#+hugo_base_dir: ../
+
+#+csl-style: /path/to/file.csl
+
+[[cite:&SomeCitation]]
+
+[[bibliography:/path/to/file.bib]]
+#+end_src
 *** Pandoc Citations
 :PROPERTIES:
 :EXPORT_FILE_NAME: pandoc-citations
@@ -2748,46 +2785,6 @@ be fixed.
 
 (Of course, open an issue whenever any ~ox-hugo~ export does not do
 things as you expect :smile:)
-*** Org-ref Citations
-:PROPERTIES:
-:EXPORT_FILE_NAME: org-ref-citations
-:EXPORT_HUGO_MENU:
-:END:
-#+begin_note
-<2022-02-10 Thu> Below instructions are out-dated. The [[https://github.com/andras-simonyi/citeproc-org][citeproc-org]]
-package repository now mentions that the package is *obsolete* as
-citation handling is now integrated into Org 9.5 in the new *oc.el*
-library.
-#+begin_quote
-As native support for citations including CSL-based export is now part
-of Org (see [[https://orgmode.org/list/87o8bcnfk9.fsf@nicolasgoaziou.fr/][the announcement]] and the relevant [[https://orgmode.org/manual/Citation-handling.html][manual section]]), and the
-most recent org-ref version also supports CSL-formatting (see [[https://www.youtube.com/watch?v=Xs59PGTfDC0][this
-video]]), citeproc-org is obsolete and will be in maintenance mode
-(reported bugs will be fixed), with only occasional backports from the
-Org-native CSL infrastructure, which is under active development. The
-recommended way of getting CSL-rendering of Org citations is therefore
-using native Org cites with the CSL export processor or using [[https://github.com/jkitchin/org-ref][org-ref
-3]].
-#+end_quote
-Related: [[*Org-Cite Citations][Org-Cite Citations]] | [[https://blog.tecosaur.com/tmio/2021-07-31-citations.html][/This Month in Org/ -- July 2021]]
-#+end_note
-
-#+begin_center
-*DEPRECATED*
-#+end_center
-
-[[https://github.com/jkitchin/org-ref][Org-ref]] citations can be exported to Hugo-compatible markdown via the
-[[https://github.com/andras-simonyi/citeproc-org][citeproc-org]] package. To enable this, simply install ~citeproc-org~
-from Melpa, and run the setup hook. With ~use-package~, this looks
-like:
-
-#+begin_src emacs-lisp
-(use-package citeproc-org
-  :ensure t
-  :after ox-hugo
-  :config
-  (citeproc-org-setup))
-#+end_src
 *** Custom Front-matter Parameters
 :PROPERTIES:
 :EXPORT_FILE_NAME: custom-front-matter

test/setup-ox-hugo.el

@@ -110,7 +110,7 @@ Emacs installation.  If Emacs is installed using
 (when ox-hugo-test-setup-verbose
   (message "ox-hugo-tmp-dir: %s" ox-hugo-tmp-dir))
 
-(defvar ox-hugo-packages '(toc-org citeproc))
+(defvar ox-hugo-packages '(toc-org citeproc org-ref))
 (when ox-hugo-install-org-from-elpa
   ;; Fri Sep 22 18:24:19 EDT 2017 - kmodi
   ;; Install the packages in the specified order. We do not want
@@ -197,6 +197,8 @@ to be installed.")
   (error "The environment variable OX_HUGO_TMP_DIR needs to be set"))
 
 (require 'oc-csl nil :noerror)          ;Auto-register csl processor
+(require 'org-ref)
+
 (require 'ox-hugo)
 (defun org-hugo-export-all-wim-to-md ()
   (org-hugo-export-wim-to-md :all-subtrees nil nil :noerror))

test/site/content-org/citation-org-ref.org

@@ -0,0 +1,25 @@
+#+title: Citation using ~org-ref~
+
+#+hugo_base_dir: ../
+#+author:
+
+#+filetags: org_ref csl citations bibliography
+
+#+csl-style: cite/csl/apa.csl
+
+#+macro: oxhugodiscuss =ox-hugo= Discussion #[[https://github.com/kaushalmodi/ox-hugo/discussions/$1][$1]]
+
+#+begin_description
+Test citation CSL using ~org-ref~.
+#+end_description
+
+{{{oxhugodiscuss(561)}}}
+
+[[cite:&OrgCitations]]
+
+[[bibliography:cite/bib/orgcite.bib]]
+
+#+bind: org-export-before-parsing-hook (lambda (_) (org-ref-process-buffer 'html))
+# Local Variables:
+# org-export-allow-bind-keywords: t
+# End:

test/site/content/posts/citation-org-ref.md

@@ -0,0 +1,16 @@
++++
+title = "Citation using org-ref"
+description = "Test citation CSL using `org-ref`."
+tags = ["org-ref", "csl", "citations", "bibliography"]
+draft = false
++++
+
+`ox-hugo` Discussion #[561](https://github.com/kaushalmodi/ox-hugo/discussions/561)
+
+(<a href="#citeproc_bib_item_1">Org et al., 2021</a>)
+
+## Bibliography
+
+<style>.csl-entry{text-indent: -1.5em; margin-left: 1.5em;}</style><div class="csl-bib-body">
+  <div class="csl-entry"><a id="citeproc_bib_item_1"></a>org, m., Syntax, C., List, M., &#38; Effort, T. (2021). Elegant citations with org-mode. <i>Journal of Plain Text Formats</i>, <i>42</i>(1), 2–3.</div>
+</div>