This repository provides a bare minimum of files to generate a tidy academic
paper with markdown that, nevertheless, is published as both a Microsoft Word
.docx and as a
Please have installed, for maximal compatibility with this README:
- Git, for getting these files and putting your own essay under version control.
- Atom, for editing your plain text files.
- Pandoc, for converting Markdown to Word and TeX.
- A TeX distribution, such as MiKTeX for Windows or MacTeX for MacOS, for typesetting your document.
- Zotero, for managing citations.
- Better BibTeX, a plugin that improves Zotero .
- Fork this “repo”
- Clone your forked copy of the repo (use the “GitHub: Clone” command in Atom, accessed via the Command Palette).
Understand the Repo
sections/: a folder containing a bunch of Markdown files that make up the content of your essay.
a-long-story.md: a Markdown file
intro.md: a Markdown file
section-one.md: a Markdown file
.gitignore: a list of files for Git to ignore. You can also ignore this file.
bibliography-preamble.tex: a short TeX file that sets the formatting for your bibliography.
bibliography.bib: a BibLaTeX-formatted database of all of the sources you will be citing. It is an exported version of this Zotero collection. For more, see below.
metadata.yml: a YAML file containing the metadata (author, title, margins) regarding the essay. See below.
process.sh: PowerShell and shell scripts that convert your Markdown content into
README.md: this file.
sections.txt: a file containing a list of files from inside the
sectionsfolder above, in the order in which they should appear in the final document.
template.tex: the underlying TeX template for generating the pdf.
- On MacOS and Linux, execute
sh process.shfrom within the repo root directory, which you can do in Atom by launching a terminal from within the editor.
- On Windows, execute
.\process.ps1from within the repo root directory, which you can do in Atom by launching a terminal from within the editor.
These commands will create two “finished” files:
output.pdf. Additionally, for reference purposes, it will put a TeX file,
output.tex in the
tmp directory, which is created on the fly.
Writing Scholarly Markdown
The two main differences between writing regular Markdown and scholarly Markdown are the introduction of footnotes and citations.
Footnotes are written inline with the text itself. This is similar to the way applications like Scrivener treat footnotes. In other words, you write them like this:
It was important to remember that, during this battle, the sides were hardly evenly matched.^[In fact, contemporary sources posit that one side had nearly ten times as many soldiers.] Nevertheless, the battle started precisely at noon.
Note the syntax: a
^, followed by the contents of the footnote enclosed in
If your footnotes need to grow to multiple paragraphs, please see the Pandoc documentation for “regular footnotes” (those described above are “inline footnotes”).
bibliography.bib, is written in the
BibLaTeX. Every entry to the database
begins with its type (
@book, for example), followed by its citation key.
In the case of the
bibliography.bib included in this repo, the very first
citation key is
When exporting a collection from Zotero as BibLaTeX (by right- or
control-clicking on the collection and choosing “Export Collection…”), Zotero
will auto-create citation keys of the format
Citing a work in the
.bib file is done using the citation key. In Markdown,
the typical format to do so is:
The narrator refers to Guideo Volkbein as “both a gourmet and a dandy, never appearing in public without the ribbon of some quite unknown distinction tinging his buttonhole with a faint thread”[@barnes_nightwood_1995 3].
The citation syntax is rather flexible and forgiving. The Pandoc documentation provides a few other examples:
Blah blah [see @doe99, pp. 33–35; also @smith04, chap. 1]. Blah blah [@doe99, pp. 33-35, 38-39 and *passim*]. Blah blah [@smith04; @doe99].
Long citation keys can be cumbersome and can be difficult to remember.
Installing the Better BibTeX
plugin for Zotero will let you define citation keys from within Zotero itself
by adding a line
bibtex: citation-key in the “Extras” field in Zotero. That
is how, in the default
bibliography.bib, the standard edition of Nightwood
has a citation key of simply
Finally, often users will have one, giant .bib file that represents every
citation they have saved. If this is the case for you, then, obviously, the
bibliography key needs to be changed in
metadata.yml to point to that
file. However, in that case, you can also benefit from using the
autocomplete-bibtex plugin for
Atom that will auto-suggest citations for you.
metadata.yml file contains information that is passed both to Pandoc
itself and to LaTeX via the settings in
title: This is the title of the essay or chapter.
author: This is an array of potential authors, with one listed. Each author can have three keys, of which the latter two can be blank:
name: The author’s name
affiliation: The author’s academic affiliation
bibliography: This indicates to Pandoc where the BibLaTeX
link-citations: These are specific values that Pandoc-citeproc handles. Please see the Pandoc-citeproc documentation for more information on these keys. The
cslrefers to a Citation Style Language file. By default, Pandoc-citeproc uses the
chicago-author-datestyle. See below for more information on CSL.
nocite: If set to
"@*", the entire contents of
bibliography.bibwill be printed in the bibliography, even if works remain uncited.
epigraph: This is an array of potential epigraphs, with two listed. Each epigraph should have two keys:
text: The text of the epigraph
source: The source of the epigraph
pdf-options: This is a list of options for generating the pdf. They should be somewhat self-explanatory.
font: This key, however, is a bit tricky, and it is commented out by default, because it is hard to predict what fonts are on someone’s computer. If you download and install EB Garamond, then you can uncomment the line as it is and have the pdf output typeset in EB Garamond.
font-settings: This is a subgroup of font settings that may not apply to all fonts.
Citation Style Language Files
A brief list of CSL files to download. Once you
download the file, you should drop it into the same folder as this repository
and then set the
csl key in
metadata.yml to point to the file.