Merge pull request #559 from kaushalmodi/auto-inject-citation-bibliog…

…raphy-heading

Auto-inject Bibliography heading if CSL HTML export is enabled

.github/workflows/test.yml

@@ -22,7 +22,7 @@ jobs:
           - 'snapshot'
           - '27.2'
           - '26.3'
-          - '25.3'
+          # - '25.3' # citeproc.el throws error on emacs 25.3: https://github.com/andras-simonyi/citeproc-el/issues/102
     # runs-on: ubuntu-latest
     runs-on: ${{ matrix.os }}
     continue-on-error: ${{ matrix.emacs_version == 'snapshot' }}

doc/ox-hugo-manual.org

@@ -2571,6 +2571,58 @@ based citation processing to work.
 So make sure that you don't have ~:EXPORT_HUGO_PANDOC_CITATIONS: t~ in
 your post tree or ~#+hugo_pandoc_citations: t~ in your Org file!
 #+end_note
+**** Citation Processor: CSL
+The [[https://citationstyles.org/][Citations Style Language]] (CSL) defines how the citations and
+bibliographies should be exported.
+
+Using CSL is optional, and dependent on an external package
+[[https://github.com/andras-simonyi/citeproc-el][~citeproc.el~]]. By default CSL is not enabled and the citations and
+bibliographies will be exported to Markdown in plain text i.e. without
+any emphasis, hyperlinking, etc.
+
+To enable <<<CSL-formatted exports>>>:
+1. Install ~citeproc~ from [[https://melpa.org/#/citeproc][Melpa]].
+2. Add this to the top of your Org file: ~#+cite_export: csl~
+
+That's it! The Org inbuilt library ~oc-csl.el~ will autoload
+~citeproc~ when it sees that ~#+cite_export~ keyword. With CSL
+processing enabled, the citations and bibliographies will now be
+exported in HTML embedded in the exported Markdown files.
+
+Check out the [[https://blog.tecosaur.com/tmio/2021-07-31-citations.html#using-csl][/This Month in Org/ -- July 2021]] post for more
+information.
+**** Auto-injecting /Bibliography/ heading
+#+begin_mark
+If CSL-formatted exports are enabled
+#+end_mark
+, a Markdown heading named "Bibliography" will be auto-inserted above
+the /bibliography/ section. This section is exported if the Org file
+has {{{relref(~#print_bibliography:~
+keyword,#printing-bibliography)}}}.
+
+This feature is controlled by the ~org-hugo-citations-plist~
+property list variable.
+
+This property list recognizes these properties:
+
+- :bibliography-section-heading :: /(string)/ Heading to insert before
+  the bibliography section.  The default value is "Bibliography". If
+  this property is set to an empty string, the bibliography heading
+  auto-injection is not done.
+
+  Some users might choose to customize this value to
+  "References". Here's an example of how that can be done in the Emacs
+  config:
+  #+name: code__customizing_bibliography_heading
+  #+caption: Customizing bibliography heading
+  #+begin_src emacs-lisp
+  (with-eval-after-load 'ox-hugo
+    (plist-put org-hugo-citations-plist :bibliography-section-heading "References"))
+  #+end_src
+- :bibliography-section-regexp :: /(string)/ Regular expression to
+  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~.
 *** Pandoc Citations
 :PROPERTIES:
 :EXPORT_FILE_NAME: pandoc-citations
@@ -2726,7 +2778,7 @@ Related: [[*Org-Cite Citations][Org-Cite Citations]] | [[https://blog.tecosaur.c
 
 [[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
+from Melpa, and run the setup hook. With ~use-package~, this looks
 like:
 
 #+begin_src emacs-lisp

ox-hugo.el

@@ -577,6 +577,29 @@ Some of the inbuilt functions that can be added to this list:
   :group 'org-export-hugo
   :type '(repeat function))
 
+(defcustom org-hugo-citations-plist '(:bibliography-section-heading "Bibliography"
+                                      :bibliography-section-regexp "\n\n\\(.\\|\\n\\)*?<div class=\"csl-bib-body\">"
+                                      ;;                            ^^^^ blank line before the <div> block
+                                      )
+  "Property list for storing default properties for citation exports.
+
+Properties recognized in the PLIST:
+
+- :bibliography-section-heading :: Heading to insert before the bibliography
+                                   section.
+
+- :bibliography-section-regexp :: Regular expression to find the
+                                  beginning of the bibliography section.
+
+Auto-detection of bibliography section requires installing the
+`citations' package from Melpa and adding `#+cite_export: csl' at
+the top of the Org file.
+
+If `:bibliography-section-heading' set to an empty string,
+bibliography heading auto-injection is not done."
+  :group 'org-export-hugo
+  :type '(plist :key-type symbol :value-type string))
+
 
 
 ;;; Define Back-End
@@ -1932,6 +1955,19 @@ holding export options."
                             ;; (`).
                             "\\([[:space:]>]\\|\n\\)+\\([^-#`]\\)")
                     " \\2" contents)))
+
+    ;; Auto-inject Bibliography heading.
+    (let ((bib-heading (org-string-nw-p (plist-get org-hugo-citations-plist :bibliography-section-heading))))
+      (when (and bib-heading (featurep 'citeproc))
+        (let* ((bib-regexp (plist-get org-hugo-citations-plist :bibliography-section-regexp))
+               (loffset (string-to-number
+                         (or (org-entry-get nil "EXPORT_HUGO_LEVEL_OFFSET" :inherit)
+                             (plist-get info :hugo-level-offset))))
+               (level-mark (make-string (+ loffset 1) ?#)))
+          (setq contents (replace-regexp-in-string
+                          bib-regexp
+                          (format "\n\n%s %s\\&" level-mark bib-heading) contents)))))
+
     ;; (message "[org-hugo-inner-template DBG] toc-level: %s" toc-level)
     (org-trim (concat
                toc

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))
+(defvar ox-hugo-packages '(toc-org citeproc))
 (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
@@ -157,7 +157,7 @@ Emacs installation.  If Emacs is installed using
                            "http"
                          "https"))
              (melpa-url (concat protocol "://melpa.org/packages/")))
-        (add-to-list 'package-archives (cons "melpa" melpa-url) :append) ;For `toc-org'
+        (add-to-list 'package-archives (cons "melpa" melpa-url) :append) ;For `toc-org', `citeproc'
         )
 
       ;; Delete element with "nongnu" car from `package-archives'.
@@ -196,7 +196,7 @@ to be installed.")
         (setq ox-hugo-missing-packages '())))
   (error "The environment variable OX_HUGO_TMP_DIR needs to be set"))
 
-(require 'org-id)
+(require 'oc-csl nil :noerror)          ;Auto-register csl processor
 (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-csl.org

@@ -0,0 +1,23 @@
+#+title: Citation CSL
+
+#+hugo_base_dir: ../
+#+author:
+
+#+bibliography: cite/bib/orgcite.bib
+#+cite_export: csl
+
+#+filetags: org_cite csl citations bibliography
+
+#+macro: oxhugoissue =ox-hugo= Issue #[[https://github.com/kaushalmodi/ox-hugo/issues/$1][$1]]
+
+#+begin_description
+Test citation CSL using ~oc.el~ + ~citeproc.el~.
+#+end_description
+
+{{{oxhugoissue(558)}}}
+
+[cite:@OrgCitations]
+
+Below, the "Bibliography" heading will be auto-inserted.
+
+#+print_bibliography:

test/site/content/posts/citation-csl.md

@@ -0,0 +1,18 @@
++++
+title = "Citation CSL"
+description = "Test citation CSL using `oc.el` + `citeproc.el`."
+tags = ["org-cite", "csl", "citations", "bibliography"]
+draft = false
++++
+
+`ox-hugo` Issue #[558](https://github.com/kaushalmodi/ox-hugo/issues/558)
+
+(<a href="#citeproc_bib_item_1">org et al. 2021</a>)
+
+Below, the "Bibliography" heading will be auto-inserted.
+
+## 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, mode, Citation Syntax, Mailing List, and Time Effort. 2021. “Elegant Citations with Org-Mode.” <i>Journal of Plain Text Formats</i> 42 (1): 2–3.</div>
+</div>