This is an example markdown document with some details about how to do scholarly writing in Markdown using Atom. We're using Atom because it's a free, easy-to-use text editor that we can extend with packages to save us time and effort.

Before reading on, download and install Atom from https://atom.io/

After opening Atom, install these packages into Atom by pressing Ctrl + , then click on 'Install', then enter these package names one by one, and click 'install' for each package:

• autosave protects our work (Settings -> check the box to enable)
• highlight-selected helps with editing
• language-markdown syntax highlighting
• linter-retextjs basic prose feedback
• markdown-preview-enhanced preview the document (Ctrl + M to show/hide)
• pandoc-convert installs Pandoc for us
• platformio-ide-terminal easily use the terminal (Ctrl + ` to show/hide)
• wordcount count the words (Settings -> turn it on after installing)

Outside of Atom, you will need to install:

• Zotero and its connector for Chrome to collect and manage citations
• Git to keep track of different versions of our documents

There are two simple methods from getting scholarly references into your Markdown document: with Google Scholar, or with Zotero.

To start with Google Scholar, search for the scholarly sources that you need for your research. In the list of results, click on the small double quotation icon at the bottom of the list item that you want to cite. In the 'Cite' pop-up, click 'BibTeX', then copy all the text you see, and paste it into your .bib file. The schematic below summarises the steps when getting your citations directly from Google Scholar:

To start with Zotero and its connector for Chrome, browse to the webpage of the journal article you want to cite. Then click on the 'Save to Zotero' toolbar button on Chrome. This will download the citation and the PDF to your computer. Then you can export the bibliographic details from Zotero in BibTeX format and paste them into your .bib file. The advantage of this method over the Google Scholar method is that you have the citation stored on your computer in Zotero, so you can easily find and reuse it. The schematic below summarises the steps for getting your citations using Zotero:

Whichever method you use, you will end up with a reference in your .bib that looks something like this:

@article{marwick_computational_2016,
year={2016},
issn={1072-5369},
journal={Journal of Archaeological Method and Theory},
doi={10.1007/s10816-015-9272-9},
title={Computational Reproducibility in Archaeological Research: Basic Principles and a Case Study of Their Implementation},
url={http://dx.doi.org/10.1007/s10816-015-9272-9},
publisher={Springer US},
keywords={Reproducible research; Computer programming; Software engineering; Australian archaeology; Open science},
author={Marwick, Ben},
pages={1-27},
language={English}
}

On the first line of this reference we see marwick_computational_2016, this is the 'BibTeX key'. We paste the BibTeX key into our Markdown text to cite this reference. See below for more on how to format in-text citations in Markdown.

Assuming that you have a .bib file in the same directory as the .md or .Rmd file, then in your Markdown document, type [ then @ and paste in th BibTeX key of the item you want to cite, like this: [@marwick_computational_2016]

Look at the YAML front matter of this file to see how to link your .bib file to your .md file, it should be something like this:

---
csl: chicago-author-date.csl
bibliography: bibliography.bib
---

You need both of these files in the same directory as your .md file. The .csl file sets the style of your in-text citations and the items in the reference list. We can get different ones from here: https://github.com/citation-style-language/styles (be sure to download the raw, plain text file, not the website). The .bib is one you make by putting the full bibliographic details from your Zotero library into this .bib file that lives with your .md file.

With minor modifications we can get all the usual configurations of citations in our sentences (from RStudio):

Blah blah [see @marwick_computational_2016, pp. 33-35; also @marwick2018standard, ch. 1].

Blah blah [see @marwick_computational_2016, pp. 33-35; also @marwick2018standard, ch. 1].

Blah blah [@marwick_computational_2016, pp. 33-35, 38-39 and *passim*].

Blah blah [@marwick_computational_2016, pp. 33-35, 38-39 and passim].

Blah blah [@marwick2018standard; @marwick_computational_2016].

Blah blah [@marwick2018standard; @marwick_computational_2016].

A minus sign (-) before the @ will suppress mention of the author in the citation. This can be useful when the author is already mentioned in the text:

Marwick and Piilar Birch say blah [-@marwick2018standard].

Marwick and Piilar Birch [-@marwick2018standard] say blah

You can also write an in-text citation, as follows:

@marwick2018standard says blah.

@marwick2018standard says blah.

@marwick2018standard [p. 33] says blah.

@marwick2018standard [p. 33] says blah.

We often want to check that our citations are working as expected while we are writing so we can catch mistakes that might creep in.

Go to Settings -> Packages -> markdown-preview-enhanced and first, check the box for 'Use Pandoc parser', then, second, look for the option 'Pandoc options: Commandline Arguments' and paste in this text: --filter=pandoc-citeproc

After this, when writing Markdown we can press Control + shift+ m and we'll see a panel with the citations processed correctly, for example, @marwick_computational_2016

To convert the Markdown document into a MS Word docx document on your computer, we use Pandoc via the terminal. In Atom, start the terminal with Command + shift+ t, check that the terminal in is the right directory (this will be ok if you are using an Atom project) and type in pandoc -s example.md -o example.docx --filter pandoc-citeproc

You should change the names of the .md and .docx files in that command to match your own files.

We're using Git for version control of our documents.

You can keep track of your Git database by clicking on the "Git" icon on the far right of the lower status bar. You can do a commit from that button.

Go to GitHub and create a new repository and add it as a remote to your project's Git repository. Then you can push from Atom.

The entire sequence is shown in this gif:

• http://u.arizona.edu/~selisker/post/workflow/
• https://programminghistorian.org/en/lessons/sustainable-authorship-in-plain-text-using-pandoc-and-markdown
• http://plain-text.co
• https://the-javascripting-english-major.org/1-environment
• https://discuss.atom.io/t/using-atom-for-academic-writing/19222
• https://hackernoon.com/lint-lint-and-away-linters-for-the-english-language-70f4b22cc73c
• Other fun Atom packages to explore: https://atom.io/users/benmarwick/stars