This article outlines a workflow for incorporating bibliographic citations/references in Markdown documents, and exporting new documents with compiled bibliographies according to specific citation styles. All tools involved in this pipeline are free, open source, and cross platform.
This guide outlines a workflow for incorporating bibliographic referencing (citations and references) in  documents. The general idea is incorporating citation keys in a Markdown document, and then rendering the bibliography by generating a new document against a bibliographic collection (`bib` file), and a citation style (`csl` file).
The following describes:
- creating and exporting a bibliography collection with [Zotero][];
- using citation keys in a Markdown document;
- getting a citation style file;
- exporting new documents (e.g. PDF, DOCX, MD, etc.) with [Pandoc][], where citations and bibliographic references are formatted as per any specific citation style.
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. [https://doi.org/10.1145/3235765.3235767](https://doi.org/10.1145/3235765.3235767).
2. [Zotero][] -- free and open source cross platform citation management software.
3. [Better Bibtex] -- "an extension forZotero...that makes it easier to manage bibliographic data, especially for people authoring documents using text-based toolchains (e.g. based on[LaTeX](https://www.latex-project.org/)/[Markdown](https://www.markdownguide.org/)").
4. [Pandoc][] -- "universal document converter"; a command line tool for converting between different document formats (e.g. Markdown to PDF or DOCX), and compiling bibliographic references.
[Chocolatey]: https://chocolatey.org/ "Free and open source package manager for Windows."
[Homebrew]: https://brew.sh/ "Free and open source package manager for macOS."
Pandoc is a command line tool that can be installed via a downloadable installer or through the terminal (see [Installing pandoc](https://pandoc.org/installing.html)).
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.
### Installation
Installing via a terminal requires a package manager (e.g. [Chocolatey][] for Windows, or [Homebrew][] for macOS).
- For Windows, using the package manager [Chocolatey] do:
```
choco install pandoc
```
- For macOS, using the package manager [Homebrew][], do:
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 [Zotero][] and [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](#cite)).
3. Save your collection, e.g. as `mycollection.bib` . The resulting file is a set of citation keys, each with its own citation metadata (you can preview the file with a text editor).
- 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 [Better Bibtex][] preferences (Zotero: Tools > Better BibTex > Open preferences). The format used in this example is `auth.lower+year`.
# Using citation keys in Markdown documents {#cite}
To add a citation in a Markdown file, just prefix a citation key (from Zotero) with the `@` sign, as in `@khaled2018`.
When the document will be compiled against a bibliography and a citation style, citation keys will be rendered according to the specified citation style *and* a reference will be added to the bibliography section for each citation.
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)
Use a provided citation style file (CSL), or download one from [the official citation style repository](https://github.com/citation-style-language/styles) (GitHub repository), or from the [Zotero Style Repository](https://www.zotero.org/styles) (search interface).
Note: Zotero features a citation style editor (Tools > Style Editor), for modifying existing citation styles if needed.
# Gather files and paths
The next step is to make a note of the paths of your Markdown document, citation style, and bibliography files, which will be used to compile a new document.
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/"
[Here you can also assemble the pandoc command for converting this document (discussed in the next sections), so that it can be easily reused.]
- 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 special characters in cases where file or directory names contain spaces.
By default, [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:
- missing/wrong citation keys: [Pandoc][] will list all citation keys that were not found in the supplied `bib` 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.
See also [Pandoc demos](https://pandoc.org/demos.html), [Getting started with pandoc](https://pandoc.org/getting-started.html), and [pandoc options manual][].
