Getting Started
A quick example
Markdown is a simple and efficient format to write academic documents. It can easily handle citations, images, equations, and cross referencing. Moreover, as a pure text format, you can edit it with any editor (eg. Atom) and it plays well with versioning tools.
To quick start your project, you can ask pandemic to prepare a boilerplate for you:
pandemic scaffold demo
Check here to see how you can define your own scaffolding boilerplates.
Once you have edited your manuscript.md file you can simply generate a publication ready document:
pandemic publish manuscript.md
Voilà! You now have in the _public folder a compiled version of your manuscript.
Help
To list all the actions Pandemic responds to:
pandemic --help
Output format
You can export your document to any format supported by Pandoc: .docx, .html, .tex, etc.
By default, pandemic will export to .pdf format. You can easily override this default when calling pandoc, eg.:
pandemic publish manuscript.md --format docx
You can also specify the desired format in the front-matter of your markdown document:
---
pandemic:
format: docx
---
Styling
If you want to change the look of your compiled document, you will need to install recipes which contain a template and instructions to compile your document with a specific style. For example:
pandemic resource install recipe --as eisvogel https://github.com/Wandmalfarbe/pandoc-latex-template
In order to use the recipe, either specify it when calling pandemic:
pandemic publish manuscript.md --to eisvogel
Or specify the desired recipe in the front-matter of your markdown document:
---
pandemic:
recipe: eisvogel
---
You can also create your own recipe!
Bibliography
You can insert references in your markdown document using the markdown citation syntax. By default, Pandemic will look for a bibliography.bib bib file in the source folder to parse the references. You can however override this default by specifying the relative path to you .bib files in the front-matter:
---
bibliography: myReferences.bib
---
You can also provide multiple .bib files if needed:
---
bibliography:
- myReferences.bib
- ../shared/references.bib
---
Example
manuscript.md
As demonstrated by @doe2018, ...
# References
bibliography.bib
@article{doe2018,
author={Doe, John},
year={2018},
title={A fantastic paper}
}
Will generate using pandemic:
manuscript.pdf
As demonstrated by Doe (2018), ...
References
Doe, John. 2018. “A Fantastic Paper.”
Cross referencing
Pandemic automatically extend the classical markdown syntax with crossref syntax. This allow you to give labels to image, equations, tables, etc. When then referencing those labels, Pandemic will replace the labels by properly numbered references, eg.:
{#fig:barGraph1}
See figure @fig:barGraph1.
Will produce a document with the figure barGraph1.jpg titled “Figure 1” and a text saying See figure 1.
You will find more example in the demo (see above) and on the crossref website.
Mustache
You can use Mustache templating in your document. You simply need to specify one or multiple .json or .yaml files which contain the data to be parsed, and Pandemic will automatically take care of it. By default, Pandemic will also look for a results.json file in the same directory as the compiled document and try to mustache it. You can however override this default in the front-matter of your document:
---
mustache: myResults.json
---
or
---
mustache:
- myResultsA.yaml
- myResultsB.json
---
Example
manuscript.md
There was an effect ($\beta$ = {{ exp1.beta }}, p = {{ exp1.pvalue }}).
results.json
{
"exp1": {
"beta": 2.80,
"pvalue": 0.036
}
}
Will generate using pandemic:
manuscript.pdf
There was an effect of treatment (β = 2.80, p = 0.036).