284 lines
14 KiB
Markdown
284 lines
14 KiB
Markdown
---
|
||
title: "Markdown bibliographic referencing workflow"
|
||
date: "2023-07-14T20:21:29+03:00"
|
||
author: "anybody"
|
||
contributors: ["constantinos-miltiadis.md"]
|
||
draft: false
|
||
keywords:
|
||
- guide
|
||
- markdown guide
|
||
abstract: |
|
||
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.
|
||
---
|
||
|
||
[Better Bibtex]: https://retorque.re/zotero-better-bibtex/ "an extension for Zotero for managing bibliographic data, especially text-based document authoring toolchains"
|
||
[Zotero]: https://www.zotero.org/ "free and open source, cross-platform citation management software."
|
||
[Pandoc]: https://pandoc.org/ "universal document converter"
|
||
|
||
|
||
<!-- try
|
||
output: html_document
|
||
bibliography: references.bib
|
||
-->
|
||
|
||
# Introduction
|
||
|
||
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.
|
||
|
||
All tools involved 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. [https://doi.org/10.1145/3235765.3235767](https://doi.org/10.1145/3235765.3235767).
|
||
|
||
# Requirements
|
||
|
||
1. Some Markdown editor for authoring Markdown documents (see ).
|
||
2. [Zotero][] -- free and open source cross platform citation management software.
|
||
3. [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 [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.
|
||
|
||
|
||
## Pandoc installation & upgrade {#pandoc-install}
|
||
|
||
[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:
|
||
```
|
||
brew install pandoc
|
||
```
|
||
|
||
### Upgrade
|
||
|
||
To upgrade [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 pandoc with the command:
|
||
```
|
||
pandoc --version
|
||
```
|
||
|
||
# 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 [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)).
|
||
|
||
4. To export your reference collection, select the collection, right-click > Export Collection, select **Better BibLaTeX** (uncheck all options; background export optional):
|
||
|
||
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).
|
||
|
||
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 [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)
|
||
|
||
|
||
# Get a citation style file (CSL)
|
||
|
||
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.]
|
||
-->
|
||
```
|
||
|
||
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 special characters in cases where file or directory names contain spaces.
|
||
|
||
# Test Pandoc and the Markdown document
|
||
|
||
Open a terminal:
|
||
- to test that [Pandoc][] works do (if the `pandoc` command is not recognized as valid go to [installation instructions](#pandoc-install):
|
||
```
|
||
pandoc --version
|
||
```
|
||
- 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 -o "/path/to/export-document.md" --atx-headers --strip-comments --wrap=preserve -t markdown_mmd-citations --standalone
|
||
```
|
||
|
||
# Compile document with bibliographic references
|
||
|
||
To compile a new document file including citations and bibliography in Markdown 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
|
||
```
|
||
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"
|
||
```
|
||
|
||
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.*
|
||
|
||
|
||
# Specify bibliography placement
|
||
|
||
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:
|
||
|
||
```
|
||
... article body ...
|
||
|
||
# Bibliography
|
||
|
||
::: {#refs}
|
||
:::
|
||
|
||
# Some other appendix
|
||
Lorem ipsum.
|
||
|
||
```
|
||
|
||
or
|
||
```
|
||
... article body ...
|
||
|
||
# Bibliography
|
||
|
||
<div id="refs"></div>
|
||
|
||
# Some other appendix
|
||
Lorem ipsum.
|
||
```
|
||
|
||
|
||
# Common errors
|
||
|
||
- 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.
|
||
|
||
<!--
|
||
```
|
||
pandoc "path/to/myarticle.md" --citeproc --bibliography "C:\Users\cmilt\Nextcloud\Aalto-NC\Publications\2301 DiGRA\bib\digraNN2.bib" --csl "C:\Users\cmilt\Nextcloud\Aalto-NC\Publications\2301 DiGRA\csl\chicago-author-date-3.csl" -o "C:\Users\cmilt\gdj-temp\mdexport\exp.md" --atx-headers --strip-comments --wrap=preserve -t markdown_mmd-citations --standalone
|
||
```
|
||
-->
|
||
|
||
# Pandoc command reference
|
||
|
||
[pandoc options manual]: https://pandoc.org/MANUAL.html#options
|
||
|
||
See also [Pandoc demos](https://pandoc.org/demos.html), [Getting started with pandoc](https://pandoc.org/getting-started.html), and [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):
|
||
- `-i "path/to/input/file.ext"` (input file, followed by path to file including file extension)
|
||
- `-o "/path/to/output/file.ext"` (output file, followed by path to file, including file extension)
|
||
- `-f` (output format, followed by option, see [pandoc options manual][])
|
||
- `-t` (output format, followed by option, see [pandoc options manual][])
|
||
- `-s`, `--standalone` (will render title, abstract, keywords, using data from front matter of the Markdown document)
|
||
- `-C`, `--citeproc` (option to render citations; will expect bibliography and csl files)
|
||
- `--bibliography "path/to/bibliography.bib"`
|
||
- `--csl "path/to/citation-style.csl"` (citation style file)
|
||
- `--atx-headers` (for common Markdown heading format)
|
||
- `--wrap=auto`|`none`|`preserve` (line wrapping options for plain text formats)
|
||
- `--strip-comments[=true|false]` (remove HTML comments)
|
||
- `--no-highlight` (Disables syntax highlighting for code blocks and inlines)
|
||
|
||
<!--
|
||
- `--metadata-file=`_FILE_
|
||
- `--markdown-headings=setext`|`atx`
|
||
- `--template=`_FILE_|_URL_
|
||
-->
|