Markdown bibliographic referencing workflow

1. Introduction¶

This guide outlines a workflow for incorporating bibliographic referencing (citations and references) in article⁄Markdown documents. The general idea is incorporating citation keys from a bibliography in a Markdown document, and then rendering citations and references by generating a new document against a bibliographic collection (bib file), and a citation style (csl file).
The steps described in the following are:

1. Installing required tools and software;
2. creating and exporting a bibliography collection with www⁄Zotero;
3. using citation keys in a Markdown document;
4. getting a citation style file;
5. exporting new documents (e.g. PDF, DOCX, MD, etc.) with www⁄Pandoc, where citations and bibliographic references are formatted as per any specific citation style.

All tools involved in this workflow are free, open source, and cross-platform.

Note: A citation is used in the body of the text to refer to some external source. A reference is placed in the “References” or “Bibliography” section of the document providing the full information for a citation. Citations and references are formatted according to a citation style. For example, for an ‘author-year’ citation style like Chicago in-text citations look like: Khaled et al. (2018), or (Khaled et al. 2018). According to the same citation style, the reference for that citation is:

• Khaled, Rilla, Jonathan Lessard, and Pippin Barr. ‘Documenting Trajectories in Design Space: A Methodology for Applied Game Design Research’. In Proceedings of the 13th International Conference on the Foundations of Digital Games, 1–10. Malmö Sweden: ACM, 2018. www⁄https://doi.org/10.1145/3235765.3235767.

2. Requirements¶

1. Some Markdown editor for authoring Markdown documents (see article⁄Markdown guide).
2. www⁄Zotero – free and open source cross platform citation management software.
3. www⁄Better Bibtex – “an extension for Zotero … that makes it easier to manage bibliographic data, especially for people authoring documents using text-based toolchains (e.g. based on www⁄LaTeX / www⁄Markdown”).
4. www⁄Pandoc – “universal document converter”; command line tool for converting between different document formats (e.g. Markdown, PDF, DOCX, epub, etc.), and compiling bibliographic references.

2.1. Pandoc installation & upgrade¶

Pandoc is a command line tool that can be installed via a downloadable installer or through the terminal (see www⁄Installing pandoc). To check if pandoc is installed, and which version is installed, open a terminal and do:

pandoc --version

If pandoc is not recognized as a valid command, go ahead and install pandoc. Otherwise, upgrade pandoc to the latest release.

2.1.1. Installation¶

Installing via a terminal requires a package manager (e.g. www⁄Chocolatey for Windows, or www⁄Homebrew for macOS).

• For Windows, using the package manager www⁄Chocolatey do:

  choco install pandoc
  

• For macOS, using the package manager www⁄Homebrew, do:

  brew install pandoc
  

2.1.2. Upgrade¶

To upgrade www⁄Pandoc, if it was installed via an installer, download and run the latest installer.
If it was installed via terminal, it can be upgraded with a single command.

• For Windows:

  choco upgrade pandoc
  

• For macOS:

  brew upgrade pandoc
  

Verify the version of your Pandoc installation with the command:

pandoc --version

3. Create and export a bibliography collection¶

This section outlines how to create a bibliography collection in Zotero and export it to a bib file.

1. In Zotero, create a new collection (titled say mycollection).
2. Add to your collection all items you want to reference (by drag and drop to collection, or right click > Add to Collection).
3. With www⁄Zotero and www⁄Better Bibtex installed, each entry in your Zotero database should have a unique citation key displayed at the top of its Info section (image below). Use this key as in @key (or @khaled2018) to cite this item in your Markdown document (§⁄further instructions below).
   
4. To export your reference collection, select the collection, right-click > Export Collection, select Better BibLaTeX (uncheck all options; background export optional):
   
   
5. Save your collection (e.g. mycollection.bib). The resulting file is a dictionary of citation keys, each with its own citation metadata (you can preview the file with a text editor).

Notes:

• In case you modified your Zotero collection (e.g. added/removed items or edited existing items), re-export the collection and overwrite the previous bib file.
• Opt for the BibLaTeX export format. The BibTeX export format will omit URLs associated with an entry!
• The format of citation keys can be changed in the www⁄Better Bibtex preferences (Zotero: Tools > Better BibTex > Open preferences). The format used in this example is auth.lower+year.

4. Using citation keys in Markdown documents¶

To add a citation in a Markdown file, just prefix a citation key (from Zotero) with the @ sign, as in @khaled2018.

Eventually, as described in the following steps, when the document is compiled (against a bibliography and a citation style), citation keys will be rendered according to the specified citation style, and a bibliographic reference will be added to the bibliography section of the document, per each unique cited document.

For author-year type citation styles:

• To add parentheses to a reference use square brackets, as in [@khaled2018] –> “(Khaled et al. 2018)”)
• For citing multiple sources at once separate keys with semicolons, as in [@khaled2018;@graziano2019] –> “(Khaled et al. 2018; Graziano et al. 2019)”
• To supress the author name (in author-date citation styles) do [-@khaled2018] eg. “According to Khaled and colleagues [-@khaled2018]” will render as “According to Khaled and colleagues (2018)”)
• To add a page or a note before or after a citation do [see @graziano2019, p.125] –> (see Graziano et al. 2019, p.125)

5. Get a citation style file (CSL)¶

Use a provided citation style file (CSL), or download one from www⁄the official citation style repository (GitHub repository), or from the www⁄Zotero Style Repository (search interface).

Notes:

• www⁄Zotero includes a few CSL files for popular citation styles. These are located in the styles directory of the Zotero Data Directory (Zotero > Edit > Preferences > Advanced > Show Data Directory).
• Zotero features a citation style editor (Tools > Style Editor), for modifying existing citation styles if needed.

6. Gather files and paths¶

The next step is to gather all required files that will be used to compile a new document (Markdown document, citation style, and bibliography files) and make a note of their file paths. In addition, make sure that the path of any image referenced in the Markdown document is correct.

Good practices:

• Gather your Markdown document, bibliography, and CSL files in the same directory, e.g. /mydocument/.
• Place images inside a subdirectory, e.g. /mydocument/graphics/
• Make a subdirectory for exporting documents e.g. /mydocument/export/
• Avoid using spaces in directory or file names.
• It is recommended to write down these paths either in a comment section inside your document, or in a separate text file, as in:

  <!-- Exporting notes 
  
  Markdown document (md):  
  "/path/to/mydocument/my-article.md"
  
  Bibliography file (bib): 
  "/path/to/mydocument/mycollection.bib"
  
   Citation style file (csl): 
  "/path/to/mydocument/reference-style.csl"
  
  Export directory: 
  "/path/to/mydocument/export/"
  
  Pandoc export command: ...  
  -->
  

Notes:

• File paths can be either absolute (e.g. c:/users/me/some-folder/some-file.md), or relative (e.g. /some-folder/some-file.md). However, for relative paths pandoc commands will need to be executed from the base directory of these relative paths.
• An easy way to get the absolute path of a file or directory, is to drag and drop it into a terminal, then select the path that will appear, right click, and copy.
• Enclosing file paths within “quotes” is optional. However, doing so can bypass the need for escape characters in cases where file or directory names contain spaces.

7. Test Pandoc and Markdown document¶

Open a terminal:

• first, to check that www⁄Pandoc is in order do:

  pandoc --version
  

  If the pandoc command is not recognized as valid go to §⁄installation instructions.
• to test that your Markdown document is in order do (this will not compile the bibliography):

  For docx export:
  pandoc 	"/path/to/mydocument/my-article.md" -o "/path/to/mydocument/export/my-article.docx"
  
  or for pdf export:
  pandoc "/path/to/mydocument/my-article.md" -o "/path/to/mydocument/export/my-article.pdf"
  
  or for Markdown export: 
  pandoc  "path/to/my-article.md" -o "/path/to/export-document.md" --atx-headers --strip-comments --wrap=preserve -t markdown_mmd --standalone
  

8. Compile document with bibliographic references¶

To compile a new document including citations and bibliography add the options:

To compile to PDF do:

pandoc "path/to/myarticle.md" --citeproc --bibliography "/path/to/mycollection.bib" --csl "/path/to/reference-style.csl" -o "/path/to/export-document.pdf"

Note: Conversions to PDF format require a LaTeX installation.

To compile to DOCX do:

pandoc "path/to/myarticle.md" --citeproc --bibliography "/path/to/mycollection.bib" --csl "/path/to/reference-style.csl" -o "/path/to/export-document.docx"

To compile to DOCX using a DOCX document as reference/template add the option:

--reference-doc="path/to/reference-document.docx"

Note: Conversions to DOCX format will use Footnotes, not Endnotes.

To compile to a new Markdown document (with references) do:

pandoc "path/to/myarticle.md" --citeproc --bibliography "/path/to/mycollection.bib" --csl "/path/to/reference-style.csl" -o "/path/to/export-document.md" --atx-headers --strip-comments --wrap=preserve -t markdown_mmd-citations --standalone

The additional options

9. Common Pandoc compilation errors¶

Pandoc will not compile in case of errors. Some common errors include:

• missing/wrong citation keys: www⁄Pandoc will list all citation keys that were not found in the supplied bibliography file. Correct any potential citation key misspellings, or recompile your bibliography collection to include the missing citations.
• file not found: check file paths
• cannot write/open file: Pandoc is not able to overwrite files (such as PDF or DOCX) while they are open by other software.

10. Pandoc command reference¶

See also:

• www⁄Pandoc demos,
• www⁄Getting started with pandoc, and
• www⁄pandoc options manual.

A basic pandoc command example is:

pandoc "path/to/input.txt" -o "path/to/output.docx"

Additional options can be added to this command pattern to specify export parameters. Here is a brief list of some commonly used pandoc options (enclosing file paths inside quotation marks is optional):

11. Specify bibliography placement¶

By default, www⁄pandoc will insert the bibliography at the end of the document. To force the bibliography to render at a specific location if needed – for example before endnotes or appendix sections – add the following to the target location for your bibliography:

... article body ...

# Bibliography 

::: {#refs}
:::

# Some other appendix
Lorem ipsum. 

or

... article body ...

# Bibliography 

<div id="refs"></div>

# Some other appendix
Lorem ipsum.