Bibliographic Citations

Thanks to the amazing Pandoc, markstat now supports bibliographic references. T Make sure your software is up-to-date, using Pandoc 2.11 or higher and markstat 2.6 or higher. The short script below illustrates the main ideas.

---
title: Literate Data Analysis
author: Germán Rodríguez
date: 1 June 2017
bibliography: cite.bib
---

Donald Knuth [-@knuth84] is a strong believer in documenting computer
programs and originated the term *literate programming*. This concept
is even more important in data analysis, where documenting each step
in data collection, processing and analysis is crucial [see @leisch02;
@rossini01]. 

## References

The script uses a YAML metadata block with a bibliography entry referring to a BibTeX database; in this case cite.bib, which has three sample references. For example the entry for Knuth’s paper appears below. The complete file is here.

@article{knuth84,
    author  = "Donald Knuth",
    title   = "Literate Programming",
    journal = "The Computer Journal",
    volume  = 27,
    number  = 2,
    pages   = "97--111",
    year    = 1984
}

Each entry has a unique key and we can cite it using the syntax [@key]. The citation may include a prefix [see @key] and/or a locator [@key, page 101]. If the name has been mentioned already use [-@key]. You may also use just @key with author-year formats (read about styles below).

When you run markstat add the bibliography option. The command will coordinate with Pandoc to resolve all the citations and include them in your dynamic document.

The HTML output for this example, generated with markstat using cite, bib, is here and is shown below

Citation Styles

The default style is the Chicago Manual of Style author-date format, but you can use any style available in Citation Style Language (CSL), of which there are more than 8,000 listed in the Zotero Style Repository. To change style download the .csl file and add a reference to it in the YAML block. For example to change to the IEEE style I downloaded proceedings-of-the-ieee.csl from the repository to my working directory, and edited the metadata to read

---
title: Literate Data Analysis
author: Germán Rodríguez
date: 1 June 2017
bibliography: citations.bib
csl: proceedings-of-the-ieee.csl
---

Saving the file as cite2.stmd and running markstat using cite2, bib results in the output here, also shown below:

Note that the only change in the script was the addition of the csl line in the metadata.

When citing entries you may take a shortcut such as @Knuth84 if you know you will be using an author-date style, but Knuth [-@knuth84] may be better. It yields the same output for author-date, but includes the name with numeric formats, rendering Knuth [1] for the IEEE style and Knuth¹ for the AMA style, instead of just [1] or ¹.