Support Pandoc link-citations meta-data; add test

Ref: #177

doc/ox-hugo-manual.org

@@ -2081,6 +2081,10 @@ one of the specified bibliography files.
 #+begin_note
 Users need to have the ~pandoc~ executable present in their ~PATH~.
 #+end_note
+
+When one or more citations are found by Pandoc, a top-level
+"References" section with matching references is automatically added
+at the very end of the post.
 **** Enabling
 Pandoc based citation parsing is enabled by setting the
 ~#+hugo_pandoc_citations:~ keyword or ~:EXPORT_HUGO_PANDOC_CITATIONS:~
@@ -2103,8 +2107,17 @@ the Org file directory./
 ~nocite~ is a special Pandoc-specific meta-data which can be used to
 add extra citations even when they are not referenced in the post. It
 is set like any other list-type custom front-matter parameter
-(i.e. ~:LIST_PARAM '(ELEMENT1 ELEMENT2)~).
+(i.e. ~:LIST_PARAM '(ELEMENT1 ELEMENT2)~). See its example [[#pandoc-citations-example][below]].
+**** Link citations
+~link-citations~ is a special Pandoc-specific meta-data which, when
+set to ~true~, enables linking of the citations in the post body to
+the corresponding reference in the "References" section. It is set
+like any other single-value custom front-matter parameter
+(i.e. ~:LIST_PARAM VALUE~). See its example [[#pandoc-citations-example][below]].
 **** Example
+:PROPERTIES:
+:CUSTOM_ID: pandoc-citations-example
+:END:
 Here is a mini-example using Pandoc Citations:
 #+begin_src org
 ,* Citations Example
@@ -2113,6 +2126,7 @@ Here is a mini-example using Pandoc Citations:
 :EXPORT_HUGO_PANDOC_CITATIONS: t
 :EXPORT_BIBLIOGRAPHY: bib/bib1.bib, bib/bib2.bib
 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: :nocite '(@cite3 @cite4)
+:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :link-citations true
 :END:
 Here is a test example file with an in-text citation where someone
 important says something important (e.g. @cite1). And here is

ox-hugo-pandoc-cite.el

@@ -45,7 +45,7 @@ These arguments are added to the `pandoc' call in addition to the
 arguments.")
 
 (defvar org-hugo-pandoc-cite-pandoc-meta-data
-  '("nocite" "csl")
+  '("nocite" "csl" "link-citations")
   "List of meta-data fields specific to Pandoc.")
 
 (defvar org-hugo-pandoc-cite--run-pandoc-buffer "*Pandoc Citations*"

test/site/content-org/all-posts.org

@@ -4656,6 +4656,18 @@ See [[#citation-example-section-2]].
 :CUSTOM_ID: citation-example-section-2
 :END:
 Content in section 2.
+** Citation Linking                                          :link_citations:
+:PROPERTIES:
+:EXPORT_FILE_NAME: citation-linking
+:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :link-citations true
+:END:
+#+begin_description
+Auto-link citations from post body to the citation in References
+section.
+#+end_description
+Here is a test example file with an in-text citation where someone
+important says something important (e.g. @loncar2016). And here is
+another bit of blah with a footnote citation.[fn:5]
 ** No Citations                                                        :none:
 :PROPERTIES:
 :EXPORT_FILE_NAME: citations-none
@@ -6375,7 +6387,7 @@ state of Org TODO overrides that.
 :EXPORT_FILE_NAME: hugo-draft-false-todo-state-done
 :END:
 The *DONE* state of Org TODO sets ~draft~ to ~false~ for this post.
-*** HUGO_DRAFT false, no TODO state                            :property:
+*** HUGO_DRAFT false, no TODO state                                :property:
 :PROPERTIES:
 :EXPORT_FILE_NAME: hugo-draft-false-todo-state-none
 :END:

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

@@ -0,0 +1,58 @@
++++
+title = "Citation Linking"
+description = """
+  Auto-link citations from post body to the citation in References
+  section.
+  """
+tags = ["pandoc", "citations", "link-citations"]
+draft = false
++++
+
+Here is a test example file with an in-text citation where someone
+important says something important (e.g. Loncar
+([2016](#ref-loncar2016))). And here is another bit of blah with a
+footnote citation.[^fn:1]
+
+## References {#references}
+
+<div id="refs" class="references">
+  <div></div>
+
+
+<div id="ref-eilan2016">
+  <div></div>
+
+Eilan, Naomi. 2016. "You Me and the World." *Analysis* 76 (3): 311--24.
+
+</div>
+
+<div id="ref-giovanelli2016">
+  <div></div>
+
+Giovanelli, Marco. 2016. "\"\...But I Still Can't Get Rid of a Sense of
+Artificiality\" the Reichenbach--Einstein Debate on the Geometrization
+of the Electromagnetic Field." *Studies in History and Philosophy of
+Science* 54: 35--51.
+
+</div>
+
+<div id="ref-loncar2016">
+  <div></div>
+
+Loncar, Samuel. 2016. "Why Listen to Philosophers? A Constructive
+Critique of Disciplinary Philosophy." *Metaphilosophy* 47 (1): 3--25.
+
+</div>
+
+<div id="ref-thompson2016">
+  <div></div>
+
+Thompson, Morgan, Toni Adleberg, Sam Sims, and Eddy Nahmias. 2016. "Why
+Do Women Leave Philosophy? Surveying Students at the Introductory
+Level."
+
+</div>
+
+</div>
+
+[^fn:1]: See (Thompson et al. [2016](#ref-thompson2016)).