---
aastexopts: [modern]
preambleinput: ["macros.tex"]
bibstyle: aasjournal
received: "January 1, 2018"
#revised: "January 7, 2018"
#accepted: "\\today"
#submitjournal: ApJ
title: "Using Markdown and Pandoc to Write Articles in AASTeX"
shorttitle: Sample article
shortauthors: Privon and Carberry
author:
- name: George C. Privon
ORCID: 0000-0003-3474-1125
affiliation: ["Department of Astronomy, University of Florida, 211 Bryant Space Sciences Center, Gainesville, 32611 FL, USA"]
nocollaboration: 1
- name: Josiah Carberry
ORCID: 0000-0002-1825-0097
affiliation: ["Wesleyan University, Middletown, CT", "Brown University: Providence, RI"]
collaboration: "(ORCID Demonstration)"
keywords: [miscellaneous]
software: ["[pandoc](http://pandoc.org)"]
facility: ["VLT"]
abstract: |
Markdown provides a straightforward way to create articles and documentation in a form where the underlying text is easily readable, while also facilitating the generation of various other formats. This includes \TeX, HTML, docx, and PDF (via \TeX) files. This article and the associated code describe a template which can be used to write articles in Markdown and use the pandoc software to convert the markdown text into an \aastex-compatible tex file for submission to the AAS Journals. The advantage of this approach is ease of readability for the source files and flexibility in output formats.
---
# Introduction {#sec:intro}
## Markdown {#sec:markdown}
The Markdown specification was released by John Gruber in 2004^[].
Markdown was originally intended to specify a plain text format which could be converted to `html` but in which the source could easily be read.
Since its release Markdown (and its various flavors) have been extended and become widely used, and additional output formats have become supported (Section [@sec:pandoc]).
## Pandoc {#sec:pandoc}
`pandoc` is "a universal document converter"^[], originally written by John MacFarlane^[].
At present it supports 25 input formats and 47 output formats (including variations of several standards such as markdown).
Pandoc is written in the Haskell programming language and supports extensions written as filters.
This template
Note that the author can write \TeX into the markdown file and `pandoc` will happily pass it through to the finished product.
However, this may compromise alternate (non-\TeX) output formats.
For example, the \aastex `deluxetable` environment can be used, but will not properly render in non-\TeX formats.
Pandoc filers^[] may be crafted to convert simple `pandoc` tables into `deluxetable`s on the fly, if desired.
## Paper Organization
We broadly divide this article into demonstrations of how to prepare a manuscript in Markdown such that it generates nearly-submittable \TeX (Section [@sec:prep]).
This includes how to specify the article style via the YAML header of the markdown file ([@sec:style]).
We then demonstrate how to include images (Section [Images]), tables (Section [Tables]), and citations ([Citations]).
We the conclude by discussing some practical considerations for this paper writing process ([@sec:notes]).
We remind the reader that this approach can be extended to the templates of other journals by modifying the YAML header in the markdown file and the \TeX template file.
The Markdown file, `pandoc` invocation, and associated filters used to create the \TeX for this document are available at: .
# Manuscript Preparation in Markdown {#sec:prep}
## Manuscript styles {#sec:style}
## Images {#sec:images}
## Tables {#sec:tables}
This tool will pass \latex tables through pandoc to the chosen \latex parser.
Thus, any tables which are part of \aastex will work for producing pdfs.
However, those will not propagate through to other output formats with which pandoc is compatible.
This is an example of a "simple table"^[]:
Year Subscription Publication
---- -------------- -----------
1991 600 100
1992 650 105
1993 550 103
1994 450 110
1995 410 112
1996 400 114
1997 525 115
1998 590 116
1999 575 115
2000 450 103
2001 490 90
2002 500 88
2003 450 90
2004 460 88
2005 440 79
2006 350 77
2007 325 70
2008 320 65
2009 190 68
2010 280 70
2011 275 68
2012 150 56
2013 140 55
Table: ApJ costs from 1991 to 2013.
## Citations {#sec:citations}
Citations can be incorporated using the pandoc-citeproc filter^[].
These citations take the form of: `[@Astropy2018]` to correspond to [@Astropy2018].
# Notes on Preparation for Submission {#sec:notes}
## Limitations on Internal References
Naively `pandoc` does not presently support internal reference to figures or equations and does not support numbered section references.
However the `pandoc-crossref`^[] filter adds support for this (and has been used in the preparation of this document).
Note that `pandoc-crossref` uses the same syntax as `pandoc-citeproc`, the former filter must be invoked before the latter.
For example the \TeX for this document was generated with:
pandoc demo.md -s --template aastex62_template.tex -o demo.tex \
-F pandoc-crossref -F pandoc-citeproc
## Creating New Filters
`pandoc` supports user-written filters.
We have already seen two filters, `pandoc-citeproc` and `pandoc-crossref`.
These filters enable customizable processing of documents during conversion and can be written in Haskell, lua, or python^[Using either the `panflute` or `pandocfilters` modules.].
With output formats besides \aastex\ in mind, the acknowledgements portion of the document has been delineated in the markdown file as a top-level section.
However, is desirable to automatically convert this to a `\acknowledgements` macros when creating a \TeX file.
# Acknowledgments
G.C.P acknowledges support from the University of Florida.