├── LICENSE.md ├── README.md ├── example1.md ├── example2.md ├── linux troubleshooting.txt ├── out ├── example1.docx ├── example1.html ├── example1.pdf ├── example2.docx ├── example2.html └── example2.pdf └── res ├── bib └── bibliography.bib └── csl └── ecology.csl /LICENSE.md: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) [2019] [Andrew Marx] 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Introduction 2 | 3 | This repository is meant to be used as a template for writing research papers using pandoc and markdown. It's the solution I've found so far that I like best as an alternative to WYSIWYG solutions like Word. LaTeX is overly complicated, and solutions like RMarkdown/Bookdown are basically just this solution with more requirements to get up and running (although they have some features that some people might find useful). 4 | 5 | It is important to realize that this approach will not necessarily format everything the way you would want for a final printable document. Instead, it is meant more for improving the writing process by providing a document that is automatically formatted to resemble a manuscript. Then once the content of the paper is finished, other tools will likely be needed to cleanup the final formatting. 6 | 7 | # Instructions 8 | 9 | ## Required software 10 | 11 | ### Pandoc 12 | 13 | Pandoc is a tool for converting files from one format to another. In this case we use it to turn markdown files to pdf or html files. Instructions for installing pandoc: https://pandoc.org/installing.html 14 | 15 | ### LaTeX 16 | 17 | In order for pandoc to convert your document to a pdf, it needs LaTeX installed on your computer. Different operating systems have different options for installing LaTex. Fortunately, the pandoc installation guide given previously has recommendations for each operating system (MiKTeX for Windows, BasicTeX or TinyTeX for MacOS, and TeX Live for Linux). 18 | 19 | ### Python and pip 20 | 21 | Python is needed to install some of the pandoc filters used by this template. pip is just a tool for downloading python packages, and should be included with python. 22 | 23 | ### Filters 24 | 25 | In order for pandoc to do special things to the document, like automatically number figures and equations, and automatically format citations and bibliographies, pandoc uses filters to modify the document. 26 | 27 | The *pandoc-citeproc* filter formats the citations and bibliography so you don't have to. It may or may not be automatically included with pandoc, depending on how it was installed. 28 | 29 | The *pandoc-fignos* filter automatically numbers figures. It's a python package, so to install using pip: 30 | 31 | ``` 32 | pip install pandoc-fignos 33 | ``` 34 | 35 | The *pandoc-eqnos* filter automatically numbers equations. It's a python package, so to install using pip: 36 | ``` 37 | pip install pandoc-eqnos 38 | ``` 39 | 40 | ## File overview 41 | 42 | ## Writing the Document 43 | 44 | The examples have two distinct sections. The first is the YAML header, which is used to provide data about the document. This includes things like the title, author(s), basic formatting, locations of useful files, etc. The rest of the examples is markdown, and is where all of the written content of the paper is located. 45 | 46 | ### YAML header 47 | 48 | The YAML header starts and ends with three hyphens `---` 49 | 50 | The first part of the YAML should be fairly self explanatory; it provides the title, abstract, and a list of authors 51 | 52 | ``` 53 | title: "Really Cool Title" 54 | abstract: "A mind-blowing abstract." 55 | author: 56 | - First Name 57 | - Second Name 58 | - Third Name 59 | ``` 60 | 61 | The second part provides information needed for automatically formatting the references and citations 62 | 63 | ``` 64 | bibliography: 65 | - ./res/bib/bibliography.bib 66 | csl: ./res/csl/ecology.csl 67 | link-citations: true 68 | ``` 69 | 70 | The `bibliography:` option allows users to define one or more bibtex files that contain information about the papers that will be cited. Any reference manager should be able to export bibtex files for you. Papers that are not cited by the document do not need to be removed from the bibtex file; pandoc will only put cited papers in the references section. 71 | 72 | The `csl:` option provides a link to a csl file, which contains the actual information for formatting citations. In this case, the template document uses formatting guidlines from the journal Ecology. To use the format of another journal, just replace it with the csl file for another journal. The best place to begin looking for specific csl files is here: https://citationstyles.org/authors/ 73 | 74 | ### Markdown Content 75 | 76 | There are numerous guides available for learning markdown (https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet is a good one). Although the fundamentals are the same, be aware that there are some variants of markdown with special features that might not work using the setup here. 77 | 78 | #### Citations 79 | 80 | One of the coolest features of using this setup is the way citations are automatically handled. To create citations, you use the article keys in the bibtex file. These keys are unique identifies for each of your papers. Generally, your reference manager should be providing them for you, commonly in a format that includes the first authors last name followed by the year of publication, which usually makes it easy to guess them. In the case of the example bibliography included in this template, the key is *Waples2015*. There are cases where the key might not follow this exact format, such as when you have two papers from the same year by the same author. In this case, the reference manager will modify one or both to make them unique. You can also edit the keys manually, if you wish. Ultimately, you just have to be careful about double checking the citations in the produced document. 81 | 82 | Once you know the key, you perform citations one of two ways. The first is parenthetical, which is done using square brackets: `Test citation [@Waples2015].` which produces `Test citation (Waples and Allendorf 2015).` in the final document. 83 | 84 | The second way to perform a citation is without the square brackets: `Second test citation by @Waples2015.` which produces `Second test citation by Waples and Allendorf (2015).` in the final document. 85 | 86 | At the end of the document, the full citation is automatically inserted in the proper order: `Waples, R. S., and F. Allendorf. 2015. Testing for hardy-weinberg proportions: Have we lost the plot? Journal of Heredity 106:1–19.` 87 | 88 | And everything is formatted automatically for the journal Ecology using the csl file specified. 89 | 90 | Where this design becomes especially useful is when you are submitting manuscripts for different journals with different citation formats. All you have to do is specify a different csl file and run the command to produce the document. You should never have to format citations manually. 91 | 92 | #### Math 93 | 94 | Using LaTeX is a very powerful way to get very nice looking, consistently formatted mathematical symbols and equations. Here is a good introductory post on the topic: https://meta.stackexchange.com/questions/68388/there-should-be-universal-latex-mathjax-guide-for-sites-supporting-it/70559#70559 95 | 96 | To start, you can either embed math inline, or have it produced on its own line. You can then decide which math blocks have an equation number assigned to it (with the actual numbers determined automatically). Finally, you can make references to numbered equations (again, with the number part being produced automatically). 97 | 98 | #### Figure numbering and cross-reference 99 | 100 | See: https://github.com/tomduck/pandoc-fignos 101 | 102 | To mark a figure for numbering, add an identifier to its attributes: 103 | 104 | ``` 105 | ![Caption.](image.png){#fig:id} 106 | ``` 107 | 108 | Alternatively, use reference link attributes. The prefix #fig: is required. id should be replaced with a unique string composed of letters, numbers, dashes and underscores. If id is omitted then the figure will be numbered but unreferenceable. 109 | 110 | To reference the figure, use 111 | ``` 112 | @fig:id 113 | ``` 114 | 115 | #### Table numbering and cross-reference 116 | 117 | See: https://github.com/tomduck/pandoc-tablenos 118 | 119 | To mark a table for numbering, add an id to its attributes: 120 | ``` 121 | A B 122 | - - 123 | 0 1 124 | 125 | Table: Caption. {#tbl:id} 126 | ``` 127 | The prefix #tbl: is required. id should be replaced with a unique identifier composed of letters, numbers, dashes and underscores. If id is omitted then the figure will be numbered but unreferenceable. 128 | 129 | To reference the table, use 130 | ``` 131 | @tbl:id 132 | ``` 133 | 134 | #### Equation numbering and cross-reference 135 | 136 | See: https://github.com/tomduck/pandoc-eqnos 137 | 138 | To mark an equation for numbering, add an identifier to its attributes: 139 | 140 | ``` 141 | $$ y = mx + b $$ {#eq:id} 142 | ``` 143 | The prefix #eq: is required. id should be replaced with a unique string composed of letters, numbers, dashes and underscores. If id is omitted then the equation will be numbered but unreferenceable. 144 | 145 | To reference the equation, use 146 | 147 | ``` 148 | @eq:id 149 | ``` 150 | 151 | ## Generating the output 152 | 153 | ### pdf 154 | 155 | To create the pdf, use the following command: 156 | 157 | ``` 158 | pandoc example1.md -o out/example1.pdf --filter=pandoc-fignos --filter=pandoc-eqnos --filter=pandoc-tablenos --filter=pandoc-citeproc 159 | ``` 160 | 161 | If all works well, you should get a pdf document in the *out/* folder. 162 | 163 | ### HTML 164 | 165 | To create the html, use the following command: 166 | 167 | ``` 168 | pandoc example1.md -s -o out/example1.html --filter=pandoc-fignos --filter=pandoc-eqnos --filter pandoc-tablenos --filter=pandoc-citeproc --mathjax 169 | ``` 170 | 171 | If all works well, you should get a html document in the *out/* folder. 172 | 173 | *NOTE: The abstract and line numbers are not included in the html output.* 174 | 175 | ### DOCX 176 | 177 | To create the docx (doc is also available but with less customization), use the following command: 178 | 179 | ``` 180 | pandoc example1.md -s -o out/example1.docx --filter=pandoc-fignos --filter=pandoc-eqnos --filter pandoc-tablenos --filter=pandoc-citeproc --mathjax 181 | ``` 182 | 183 | If all works well, you should get a docx document in the *out/* folder. 184 | 185 | 186 | *NOTE: Line numbers are not included in the docx output and must be enabled in Word.* 187 | -------------------------------------------------------------------------------- /example1.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Really Cool Title" 3 | abstract: "A mind-blowing abstract." 4 | author: 5 | - First Name 6 | - Second Name 7 | - Third Name 8 | 9 | 10 | # Bibliography settings 11 | 12 | bibliography: 13 | - ./res/bib/bibliography.bib 14 | csl: ./res/csl/ecology.csl 15 | link-citations: true 16 | 17 | 18 | # Formatting Settings 19 | 20 | documentclass: article 21 | fontsize: 12pt 22 | geometry: margin=1.0in 23 | #geometry: "left=3cm,right=3cm,top=2cm,bottom=2cm" 24 | header-includes: 25 | - \usepackage{times} 26 | - \usepackage[mathlines,displaymath]{lineno} 27 | - \linenumbers 28 | urlcolor: blue 29 | 30 | 31 | # Output Settings 32 | 33 | output: 34 | pdf_document: 35 | toc: false 36 | number_sections: false 37 | --- 38 | 39 | 40 | # Introduction 41 | 42 | Test citation [@Waples2015] 43 | 44 | Second test citation by @Waples2015 45 | 46 | Inline math $a^2 + b^2 = c^2$ 47 | 48 | Math on it's own line: $$a^2 + b^2 = c^2$$ 49 | 50 | Math on it's own line with automatic numbering: $$a^2 + b^2 = c^2$$ {#eq:description} 51 | 52 | Referring to equation @eq:description 53 | 54 | 55 | # Methods 56 | 57 | # Results 58 | 59 | # Discussion 60 | 61 | # References 62 | 63 | *If everything is setup correctly, references are automatically appended to the end of the document* 64 | -------------------------------------------------------------------------------- /example2.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Manuscript Starting Point" 3 | abstract: "This example is based on the PLOS blog post titled *[A Brief Guide To Writing Your First Scientific Manuscript](https://blogs.plos.org/scicomm/2018/03/07/a-brief-guide-to-writing-your-first-scientific-manuscript/)*. Basic sections are setup with a brief description/questions, and your goal is to create an outline for each one as a starting point for your own manuscript. This is just part of the process described in the article, so check it out for the rest." 4 | author: 5 | - First Name 6 | - Second Name 7 | - Third Name 8 | 9 | 10 | # Bibliography Settings 11 | 12 | bibliography: 13 | - ./res/bib/bibliography.bib 14 | csl: ./res/csl/ecology.csl 15 | link-citations: true 16 | 17 | 18 | # Formatting Settings 19 | 20 | documentclass: article 21 | fontsize: 12pt 22 | geometry: margin=1.0in 23 | #geometry: "left=3cm,right=3cm,top=2cm,bottom=2cm" 24 | header-includes: 25 | - \usepackage{times} 26 | - \usepackage[mathlines,displaymath]{lineno} 27 | - \linenumbers 28 | urlcolor: blue 29 | 30 | 31 | # Output Settings 32 | 33 | output: 34 | pdf_document: 35 | toc: false 36 | number_sections: false 37 | --- 38 | 39 | 40 | # Introduction 41 | 42 | *"What did you study, and why is it important? What is your hypothesis/research question?"* 43 | 44 | - Item 45 | - Sub-item 46 | - Sub-item 47 | - Item 48 | - Item 49 | 50 | 51 | # Methods 52 | 53 | *"What techniques did you use? Each technique should be its own bullet, with sub-bullets for key details. If you used animal or human subjects, include a bullet on ethics approval. Important methodologies and materials, i.e., blinding for subjective analyses, full names of cell lines/strains/reagents and your commercial/academic sources for them."* 54 | 55 | 1. Numbered Item 56 | 1. Numbered Sub-item 57 | 1. Numbered Sub-item 58 | 1. Numbered Item 59 | - Sub-item 60 | - Sub-item 61 | 1. Numbered Item 62 | 63 | 64 | # Results 65 | 66 | *"What were your findings? Each major finding should be its own bullet, with sub-bullets going into more detail for each major finding. These bullets should refer to your figures."* 67 | 68 | # Discussion 69 | 70 | *"Summarize your findings in the context of prior work. Discuss possible interpretations. It is important to include a bullet describing the limitations of the presented work. Mention possible future directions."* 71 | -------------------------------------------------------------------------------- /linux troubleshooting.txt: -------------------------------------------------------------------------------- 1 | This file contains some stuff I had to do for getting this running on a new ubuntu-based system during summer 2020 2 | 3 | 1) by default python 2.7 is installed and used, which caused issues, possibly because it was deprecated earlier this year. I had to force ubuntu to use python3 by running "alias python=python3" in the commandline. This is only temporary, and can be made permanent by adding to .bashrc. Be warned, making it permanent may cause issues for other programs that depend on 2.7 4 | 5 | 2) Apparently it is not recommended to run pip using sudo. Additionally, it's generally more reliable to not run pip directly from the commandline, but instead to run it using python. For example: 6 | 7 | python -m pip --install --user pandoc-fignos 8 | 9 | If you get a PATH related warning, you may need to add whatever path was listed to your PATH environment variable. In my case, this was /home/username/.local/bin 10 | 11 | 3) You can use "which" to test that the pandoc packages are installed. For example: 12 | 13 | which pandoc-fignos 14 | 15 | The result should be a path showing where it is located 16 | 17 | 4) For LaTeX, I had to run: 18 | 19 | sudo apt-get install lmodern 20 | 21 | To fix an error related to sty files. 22 | -------------------------------------------------------------------------------- /out/example1.docx: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/andrewmarx/paper-template/bfe3607d08ccef327f399654c67b3ad86d3e3b5e/out/example1.docx -------------------------------------------------------------------------------- /out/example1.html: -------------------------------------------------------------------------------- 1 |

Introduction

2 |

Test citation (Waples and Allendorf 2015)

3 |

Second test citation by Waples and Allendorf (2015)

4 |

Inline math a2 + b2 = c2

5 |

Math on it’s own line:
a2 + b2 = c2

6 |

Math on it’s own line with automatic numbering:
a2 + b2 = c2
(1)

7 |

Referring to equation 1

8 |

Methods

9 |

Results

10 |

Discussion

11 |

References

12 |

If everything is setup correctly, references are automatically appended to the end of the document

13 |
14 |
15 |

Waples, R. S., and F. Allendorf. 2015. Testing for hardy-weinberg proportions: Have we lost the plot? Journal of Heredity 106:1–19.

16 |
17 |
18 | -------------------------------------------------------------------------------- /out/example1.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/andrewmarx/paper-template/bfe3607d08ccef327f399654c67b3ad86d3e3b5e/out/example1.pdf -------------------------------------------------------------------------------- /out/example2.docx: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/andrewmarx/paper-template/bfe3607d08ccef327f399654c67b3ad86d3e3b5e/out/example2.docx -------------------------------------------------------------------------------- /out/example2.html: -------------------------------------------------------------------------------- 1 |

Introduction

2 |

“What did you study, and why is it important? What is your hypothesis/research question?”

3 | 12 |

Methods

13 |

“What techniques did you use? Each technique should be its own bullet, with sub-bullets for key details. If you used animal or human subjects, include a bullet on ethics approval. Important methodologies and materials, i.e., blinding for subjective analyses, full names of cell lines/strains/reagents and your commercial/academic sources for them.”

14 |
    15 |
  1. Numbered Item 16 |
      17 |
    1. Numbered Sub-item
      2. 18 |
    2. Numbered Sub-item
      3. 19 |
    2. 20 |
  2. Numbered Item 21 |
    3. 25 |
  3. Numbered Item
    4. 26 |
27 |

Results

28 |

“What were your findings? Each major finding should be its own bullet, with sub-bullets going into more detail for each major finding. These bullets should refer to your figures.”

29 |

Discussion

30 |

“Summarize your findings in the context of prior work. Discuss possible interpretations. It is important to include a bullet describing the limitations of the presented work. Mention possible future directions.”

31 | -------------------------------------------------------------------------------- /out/example2.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/andrewmarx/paper-template/bfe3607d08ccef327f399654c67b3ad86d3e3b5e/out/example2.pdf -------------------------------------------------------------------------------- /res/bib/bibliography.bib: -------------------------------------------------------------------------------- 1 | @article{Waples2015, 2 | abstract = {Testing for Hardy–Weinberg proportions (HWP) is routine in almost all genetic studies of natural populations, but many researchers do not demonstrate a full understanding of the purposes of these tests or how to interpret the results. Common problems include a lack of understanding of statistical power and the difference between statistical significance and biological significance, how to interpret results of multiple tests, and how to distinguish between various factors that can cause statistically significant departures. In this perspective, which focuses on analysis of genetic data for nonmodel species, I 1) review factors that can cause departures from HWP at individual loci and linkage disequilibrium (LD) at pairs of loci; 2) discuss commonly used tests for HWP and LD, with an emphasis on multiple-testing issues; 3) show how to distinguish among possible causes of departures from HWP; and 4) outline some simple steps to follow when significant test results are found. Finally, I 5) identify some issues that merit particular attention as we move into an era in which analysis of genomics-scale datasets for nonmodel species is commonplace.}, 3 | author = {Waples, Robin S. and Allendorf, Fred}, 4 | doi = {10.1093/jhered/esu062}, 5 | file = {:home/andrewjmarx/.local/share/data/Mendeley Ltd./Mendeley Desktop/Downloaded/2015 - Testing for Hardy-Weinberg Proportions Have We Lost the Plot.pdf:pdf}, 6 | isbn = {0022-1503}, 7 | issn = {14657333}, 8 | journal = {Journal of Heredity}, 9 | keywords = {Genotypic ratios,Hardy-Weinberg equilibrium,Heterozygotes,Linkage disequilibrium,Multiple testing,Statistical tests}, 10 | mendeley-groups = {Best Practices/Population Genetics}, 11 | month = {jan}, 12 | number = {1}, 13 | pages = {1--19}, 14 | pmid = {25425676}, 15 | title = {{Testing for hardy-weinberg proportions: Have we lost the plot?}}, 16 | url = {https://academic.oup.com/jhered/article-lookup/doi/10.1093/jhered/esu062}, 17 | volume = {106}, 18 | year = {2015} 19 | } 20 | 21 | -------------------------------------------------------------------------------- /res/csl/ecology.csl: -------------------------------------------------------------------------------- 1 | 2 | 189 | --------------------------------------------------------------------------------