Update Pandoc Citations documentation

Fixes https://github.com/kaushalmodi/ox-hugo/issues/175.

doc/ox-hugo-manual.org

@@ -15,6 +15,7 @@
 #+macro: doc [[/doc/$1][$2]]
 #+macro: user @[[https://github.com/$1][*$1*]]
 #+macro: testtag tests tagged [[https://ox-hugo.scripter.co/test/tags/$1][$1]]
+#+macro: test-search Search the ~ox-hugo~ test site for [[https://ox-hugo.scripter.co/test/search/?q=$1]["$1"]] examples.
 
 # https://scripter.co/latex-in-html/
 #+macro: latex @@html:<span class="latex">L<sup>a</sup>T<sub>e</sub>X</span>@@
@@ -2069,27 +2070,59 @@ What do you do? ..
 You can find a bunch of examples if you search for /"Replace
 front-matter keys"/ in {{{ox-hugo-test-file}}}.
 - Those examples are exported as {{{testtag(replace)}}}.
-*** Pandoc Citation
+*** Pandoc Citations
 :PROPERTIES:
-:EXPORT_FILE_NAME: pandoc-citation
+:EXPORT_FILE_NAME: pandoc-citations
 :END:
 Pandoc based citation parsing is enabled by setting the
 ~#+hugo_pandoc_citations:~ keyword or ~:EXPORT_HUGO_PANDOC_CITATIONS:~
-subtree property to ~t~. With this property set, the exported
-front-matter is *forced to YAML*, because Pandoc needs the
-front-matter to be in YAML format to parse fields like ~csl~ and
-~nocite~.
+subtree property to ~t~.
 
 #+begin_note
-User needs to have the ~pandoc~ executable present in their ~PATH~.
+Users need to have the ~pandoc~ executable present in their ~PATH~.
 #+end_note
 
+The Pandoc Citations are prefixed with the *@* character. If the
+citation is ~@foo~, that particular /foo/ reference much be present in
+one of the specified bibliography files.
+
 Bibliography files (~example.bib~) are specified using the
 ~#+bibliography:~ keyword or ~:EXPORT_BIBLIOGRAPHY:~ subtree
-property. Multiple bibliography files can be specified
-comma-separated.
+property. *It is mandatory to specify at least one bibliography file.*
+
+Multiple comma-separated bibliography files can be
+specified. /Note that the path to these files should be relative to
+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)~).
+
+Here is a mini-example using Pandoc Citations:
+#+begin_src org
+,* Citations Example
+:PROPERTIES:
+:EXPORT_FILE_NAME: citations-example
+:EXPORT_HUGO_PANDOC_CITATIONS: t
+:EXPORT_BIBLIOGRAPHY: bib/bib1.bib, bib/bib2.bib
+:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :nocite '(@cite3 @cite4)
+:END:
+Here is a test example file with an in-text citation where someone
+important says something important (e.g. @cite1). And here is
+another bit of blah with a footnote citation.[fn:1]
+
+,* Footnotes
+
+[fn:1] See [@cite2].
+#+end_src
+
+- Note :: Above example assumes ~bib/bib1.bib~ and ~bib/bib2.bib~ to
+          exist in the same directory containing that Org file.
+
+{{{test-search(citations)}}}
 
-See [[https://pandoc.org/MANUAL.html#citations][Pandoc Manual -- Citations]] for more details.
+Also see [[https://pandoc.org/MANUAL.html#citations][Pandoc Manual -- Citations]] for more details.
 ** Meta
 :PROPERTIES:
 :EXPORT_HUGO_MENU: :menu "7.meta"