A Reproducible Manuscript Workflow With a Quarto Template

Modern computing tools allow scientists and practitioners to be efficient, transparent, and provide reproducible results (Erickson et al. 2021; Braga et al. 2023). For example, ecologists are moving away from point-and-click statistical methods and using scripting languages with code (Borregaard and Hart 2016). These changes not only make scientists more productive but also confer additional benefits to science and management at large. First, scripting allows methods to be reused by their creator. For example, scientists commonly complete the same or similar analyses on a regular basis (such as U.S. Fish and Wildlife Service 2023a), and scripting allows methods to be easily adapted and often quickly rerun with minimal formatting. Second, sharing the scripts allows others to reuse methods and recreate results when data are shared. Third, scripting provides direct evidence about what options were, or were not, selected for an analysis and data cleaning. All three of these features increase transparency in the scientific process and increase the efficiency of scientific advancement or drafting of management documents to solve important problems.

The broader scientific community increasingly has begun to understand the importance of reproducible results because the perception of a “reproducibility crisis” exists among most of the scientists surveyed across scientific fields (Baker 2016; Fanelli 2018). This lack of reproducibility also exists in natural resource fields. For example, ArchMiller et al. (2020) determined that only 17% of studies randomly selected from the Journal of Wildlife Management and the Wildlife Society Bulletin could have their analyses reproduced. On a smaller scale, Bennie and Erickson (2024) had advanced undergraduate and graduate statistics students attempt to recreate published ecological studies for class projects and none could exactly recreate results using the methods as described in publications. One reason for this lack of reproductivity is that different methods exist for analyzing data and these methods may have different assumptions. As an example, Gould et al. (2023) asked 246 scientists to analyze the same data sets and got vastly different results from the different scientists. The most extreme variation observed by Gould et al. (2023) included different estimated signs for the effect using reasonable and tenable statistical methods (for example, some people estimated a positive effect, whereas others found a negative effect using the same data but different methods). In hydrology, lack of reproducibility has raised questions of the validity of the field as a whole (Hutton et al. 2016) and has motivated exploration of challenges from other fields (Fienen and Bakker 2016). Thus, scientists increasingly seek to produce reproducible results, especially for computationally intensive projects (Borregaard and Hart 2016). Others have provided suggestions and methods for creating reproducible results in natural resources and related fields (including Borregaard and Hart 2016; Braga et al. 2023). Additionally, findable, accessible, interoperable, and reusable (FAIR) principles exist to help scientists share and produce reproducible science (Reiser et al. 2018). Likewise, professional societies, government agencies, and other organizations have produced guidelines similar to FAIR for reproducible science (for example, refer to table 1 in Erickson et al. [2021] that lists example organizations).

Many scientists use scripting languages like Python (Van Rossum and Drake 1995) or R (R Core Team 2024) for their statistical methods and analyses. For example, Erickson and Rattner (2020) determined that a plurality of authors in the journal Environmental Toxicology and Chemistry from the 2019 issue used the R computing language for analysis in their papers. However, we have observed that fewer scientists use similar tools in a reproducible “research workflow” for writing manuscripts, even though scripting environments are now enriched with code-based manuscript services, such as Quarto, knitr, Jupyter Notebooks, and Bookdown, which are primarily Markdown-based programs (Baumer and Udwin 2015; Figure 1). Advantages of Markdown-based programs over direct typesetting products like LaTeX, Word, or Pages include simplicity, readability, transparency, and embedded computation (Baumer and Udwin 2015). Specifically, code-based manuscript writing can include the option to readily incorporate formatting from templates, ease of changing templates and reference formatting, automatic populating of references on the basis of digital object identifiers (DOIs), and the ability to easily handle complex formulas (specifically embedded LaTeX syntax for formulas). Furthermore, these writing tools can be especially powerful when embedded with the code and data used in the document, which allows authors to create reproducible manuscripts that directly populate in-text tables and figures and descriptive statistics or test statistics reported in results sections.

We have observed interest (circa 2021–2023) in Markdown-based writing documents in North America and globally from our colleagues and collaborators who are natural resource managers or scientists supporting these managers. For example, the U.S. Geological Survey has a Markdown Community of Practice, and the authors of this paper have presented tutorials to this group. Additionally, this group includes members from the U.S. Fish and Wildlife Service and other agencies in the U.S. Department of the Interior such as the U.S. National Park Service. We have also discussed using Markdown-based writing tools in online conversations with others such as the U.S. Fish and Wildlife Service’s Great Lakes R Working Group. These examples motivated our creation of this paper and corresponding template.

For readers who are unfamiliar with Markdown-based writings tools, we provide a brief history here. Stanford University computer scientist Donald Knuth had trouble typesetting his mathematical equations in the late 1970s and early 1980s and this led him to create the TeX language (Knuth 1984). Building upon TeX, Leslie Lamport created LaTeX as a set of macros to make TeX easier to use (Lamport 1985). Statisticians who used LaTeX sought to readily embed statistical code, results, and figures into their LaTeX-based documents and workflows. To meet this need, the program Sweave was created to “weave” S into LaTeX (at the time, many statisticians used the S language, which inspired the R language; Leisch 2002).

Although useful, we have observed that TeX, LaTeX, and Sweave can be complicated to use, and Sweave can be especially cumbersome because it requires the source file to be compiled multiple times for a single output. TeX, LaTeX, and Sweave also may be difficult for natural resource scientists to learn because they require new software and languages outside of the more common R or Python environments. Furthermore, in the 4.5 decades since Tex was created and 4 decades since LaTeX was created, Markdown usage became ubiquitous through its integration with version control tools such as Git and common Microsoft Office tools such as Teams and Word, which include many common Markdown shortcuts for formatting text (for example, typing *, then space on a new line in either program will start a bulleted list, which is syntax borrowed from the Markdown language). Others noted these difficulties as well; thus, Yihui Xie and others created a Markdown-based program for use with R, known as R Markdown (Xie et al. 2018), that overcomes many of these limitations. R Markdown works by using the knitr package to “knit” (or compile) the R Markdown file into an output such as hyptertext markup language (HTML) files, ending with .html; Microsoft Word document files, ending with .docx; or portable document format (PDF) files, ending with .pdf (Xie 2014). Another Markdown offshoot is the roxygen2 language, which allows users in the R environment to directly convert R script files (ending with .R rather than R Markdown files ending with .Rmd) into R Markdown, which is then knit to output formats mentioned above (Wickham et al. 2022). The broader R community received R Markdown well (such as a review by Baumer and Udwin 2015), but this language also has some limitations. Most notably, the language requires R and has some minor quirks. The popularity and limitations of R Markdown led a group including Yihui Xie to create a more general program, Quarto, that works natively with many languages rather than only R (Allaire et al. 2022).

The remaining purpose of our paper is to present our Quarto template for this journal, which can be fully accessed at Erickson et al. (2024). We demonstrate some useful features including how to include figures, tables, accessibility components, and the quarto-utils package for automatic bibliography generation (Fienen and Erickson 2024). We also discuss how these tools may be applied to other situations. Although our examples tend to focus on R, Quarto works with many languages including LaTeX (for example, to typeset equations and format outputs), Python, and Julia (Figure 1). Quarto may also be used either interactively through editors such as Posit’s RStudio or Microsoft’s Visual Studio Code, or called through the terminal either directly using the Quarto command (in pseudocode quarto render my_file.qmd) or through scripts (in pseudocode such as python my_script_calling_quarto.py or Rscript my_script_calling_quarto.R). We used Quarto interactively when writing this paper, but Quarto may be used as part of scripts for automated workflows such as generating reports, summarizing model outputs, or similar tasks used to create reports.

This tutorial focuses on Microsoft Word document outputs because many journals, including the Journal of Fish and Wildlife Management, use a Word-based workflow. The Quarto documentation provides a generic journal format (https://quarto.org/docs/journals/; June 2024) and a Quarto journals GitHub repository that hosts specific templates for other journals (https://github.com/quarto-journals/; June 2024). When writing a Quarto document, the first step is to create a Quarto file that ends with .qmd extensions. Common editors that work with Quarto files include Posit RStudio (v2023.06 or newer; Posit Team 2023) and Microsoft Visual Studio Code (Microsoft 2023). RStudio also offers the benefits of creating new Quarto files from templates for journal articles, presentations, and other types of documents directly within the editor. Quarto also contains tools for generating empty templates outside of RStudio using command line tools for editing in programs such as Visual Studio Code or similar editor programs (refer to the program documentation such as https://quarto.org/docs/journals/templates.html for details of these features; June 2024). Alternatively, readers may use an existing Quarto file and edit that file. For example, people can edit the Quarto file used to generate this paper that is hosted at Erickson et al. (2024) to write their own manuscripts for journal articles or other product types such as annual reports.

Within the Quarto file, the header contains metadata in a YAML-style format (YAML is a programming language for data serialization [data serialization means specifying settings, such as formatting options in the case of Quarto] with a recursive name “YAML Ain’t Markup Language”). The Quarto file for this article contains the following metadata:

• The title listing the article’s title.

• The author listing the article’s author or authors.

• The date the Quarto file was last rendered to create the Word file.

• The output format options including the output type of docx, an option to set the figure caption locations (fig-cap-location) to the bottom, an option to keep the LaTeX output files (keep-tex: true), and the Word file used as the style template for the file (reference-doc: jfwm_template_template.docx).

• The csl file listing article’s citation style; for the Journal of Fish and Wildlife Management, this is the “Council of Science Editors, author-date format indents” with minor modifications by the authors of this paper for the Journal of Fish and Wildlife Management (council-of-science-editors-author-date-jfwm.csl). “Council of Science Editors, author-date format indents” refers to the Council of Science Editors formatting style using the Council of Science Editors style with authors and dates (such as “example fact Author et al. 2023” and in contrast to other numeric formats such as “example fact [1]”) and indented reference section paragraphs.

• The name and location of the reference file (bibliography: references.bib).

• Code to include LaTeX-based headers (header-includes:) for double spacing (\usepackage{setspace}\doublespacing) and line numbers (\usepackage{lineno}\linenumbers).

• Editor options (editor_options) telling the Markdown editor (markdown) to use a soft line wrap after each sentence (wrap: sentence).

• A list of “no citation” references (nocite) tells the Markdown to include citation items even if the item is not cited in the document. We include this because we had to manually format some inline citations to match the journal’s style.

R users may also extract code using the purl() function from the knitr R package (Xie 2014). References are added to the BibTeX file, either manually or using a script described later by pulling DOIs. Figures and tables can be added as needed, whether built locally with code chunks or called in from other sources. While writing, the author can preview the results by compiling the file to create a Word document. This also serves as a check for code mistakes that might prevent the Quarto file from compiling. The result is a Word file that may be submitted to a journal with minimal manual formatting required.

Writing Quarto documents requires a basic knowledge of Markdown. The Quarto documentation (available at https://quarto.org/; June 2024) contains tutorials to help people get started. Additionally, the Quarto document (Erickson et al. 2024) used to generate this document contains many examples for those who like to dive in and learn by doing. Writing equations requires an understanding of some of the basics of LaTeX but much less than writing entire documents in LaTeX (many online tutorials exist such as the TeX User Group’s https://tug.ctan.org/info/short-math-guide/short-math-guide.pdf; June 2024). Additionally, free graphical user interfaces such as LyX (available for all major operating systems; https://lyx.org; June 2024) provide visual tools to help create complicated equations from which the source LaTeX code can be copied and pasted into a Quarto document.

As a general observation, when Quarto documents are rendered to a .docx file format (Word documents), the Pandoc software (Dominici 2014) that renders the document is limited in formatting and style options compared with HTML or PDF files because of technical reasons beyond the scope of this paper. Hence, readers may find some solutions using search engines that will not work for this Word-based template. For example, cross-references for figures and tables do not work with this template. Likewise, we had to use nocite and manually type in some references because of formatting challenges arising from certain characters such as semicolons. Additionally, readers familiar with Quarto may find some quirky examples in the Quarto template to help meet the journal-specific formatting style. For example, the authors’ names are all listed on one line rather than using multiple entries as one might expect in the metadata section.

Integrating code into Quarto documents also helps to create reproducible results. Code may be included directly within the file, or R script files may be called into the Quarto file and knit into the final outputs using the read_chunk() function from the knitr package (Xie 2014). For example, a simple regression might be run or data plotted in a chunk of code and then the outputs included in the file. Including the code ensures the manuscript always has the most recent results and statistics if the input files are changed. Additionally, code outputs can be included and displayed inline with R and Python (https://quarto.org/docs/computations/inline-code.html; June 2024). For example, when describing a study or writing a monitoring report, one might write “We observed many birds (n = 4,341) at the refuge with a mean of 184.7 birds per day.” With this example, inline code would allow these numbers to updated dynamically if the source data or code changed when the file is rerendered. Hence, if the authors updated their input numbers in either the source data files or code, the numbers in text would change. This change may occur because the authors updated their data while writing the manuscript, or because the authors update their report on a regular basis (such as a report for an annual monitoring program).

Another tip for using Quarto to render Word documents is to use the flextable package in R (Gohel and Skintzos 2023) for creating tables rather than the popular kable() function from the knitr package (Xie 2014) and kableExtra package (Zhu 2021) because the flextable package more readily allows tables to be formatted in Word-based outputs. For example, we demonstrate how the flextable package may be used to create simple tables in Table 1 and tables with multiple columns and rows in Table 2. This table has multicolumn headers and automatically drops duplicate row names. These two aesthetic features are commonly used by scientists when describing data and can be automatically created using the flextable package in R. These features exist with kable-type tables, but do not render correctly in Word document outputs.

Finally, to edit the text style, change the jfwm_template.docx file using Word rather than directly editing the output rendered from Quarto code. This may require practitioners to become familiar with Word templates. For example, in the Journal of Fish and Wildlife Management, the first paragraph of every section lacks indentation, but the second and subsequent paragraphs in a section use a tab indent. Changing this formatting requires changing the paragraph template settings in the template Word document. Further modifications can be made to change the template by updating the Styles definitions (such as “Header 1” or “Body Text”) in the template Word document. These changes would then be shown on the output Quarto-based Word document after the template Word document is saved and the Quarto (.qmd) file is rerendered to create a Word document.

Almost all modern scientific and technical writing documents require multiple people to write, edit, or otherwise contribute to documents. During the writing process, different approaches exist for collaborative writing and editing. In an ideal world (at least the authors’ idealized world), all contributors would be comfortable using version-control software and sharing their documents that way. Realistically, this is unlikely and unreasonable on the basis of our observations. We have found the following options helpful when working with people who are uncomfortable or otherwise unable to use version-control software. First, some authors may be willing to edit Quarto files in RStudio, which provides a visual editor rather than a code-based editor and files may be emailed back and forth, similar to emailing other documents. Second, Quarto and Markdown files can be readily edited with any plain text editor, even Notepad, which comes standard with the Windows operating system, so people can simply edit the plain document without understanding Markdown or using a special Markdown editor. Third, for collaborators who would like to or require the use of conventional document files, Quarto can be compiled to a .docx file and then edited with programs like Microsoft Word or Libre Office. For small edits or high-level feedback, we have found this option to be reasonable. Fourth, software packages exist to help people collaborate with Quarto. For example, the Trackdown package allows people to share files using Google Drive and edit files using Google Docs (Kothe et al. 2021). The Trackdown package and other tools also exist for creating documents showing track changes from Quarto-based documents. Fifth, the paid commercial version of RStudio, Posit Workbench, also allows people to collaboratively edit documents in real time. Sixth, we will also sometimes write a document in Quarto and then switch to the journal’s workflow language for the final edits and “break” the connection to Quarto. For Word-based workflows, this is a Word document (ending with .docx, or .doc for some older workflows) and applies to journals such as the Journal of Fish and Wildlife Management. For LaTeX-based workflows, this is a LaTeX document (ending with .tex) and applies to journals that use LaTeX-based workflows. For example, when writing agency reports on the basis of our journal articles, we may stop using Quarto at the final stages because it is easier than continuing to update Quarto documents and hand edit the resulting Word document after each recompilation.

Using Quarto as a templating workflow does not necessarily guarantee that the resulting rendered document will be accessible to users with disabilities (such as Section 508-compliant for U.S. federal products https://www.section508.gov/; June 2024); however, there are some additional guidelines that will improve overall accessibility:

1. Use the built-in header system (e.g., # for Header 1, ## for Header 2, etc.) to create screen-readable organization in the rendered document.

2. Add ‘‘alt-text’’ to your figure elements. Alt-text is text added to provide a visual description of the figure or image and is read by screen readers. If you are using a chunk of code to create the figure, you can include a chunk argument fig.alt=‘‘…'' that will automatically create alt-text for that output. Alternatively, if you are directly adding a figure to your document, you can include alt-text within the square brackets: .

3. Follow other best practices for accessible writing and design, such as using plain language when possible, using high-contrast colors in data visualizations, and using the built-in Microsoft Word Accessibility Checker on your final rendered document.

The quarto-utils software is a Python package that assists Quarto authors in compiling and formatting references. By leveraging the https://doi.org web interface, authors can place references in their documents by only providing a DOI in place of a reference in the text. Then, using functionality in quarto-utils, the code will search the .qmd document for DOI codes, retrieve a BibTeX representation of the reference from doi.org, add the BibTeX string to a bibliography file, and convert the DOI reference in the .qmd file to a valid reference call. The author identifies a reference in the same way they would call out an existing reference using [] delimiters, but rather than providing a key that references the .bib file (such as [@Gelman2010]), they would use either _doi:thedoinumber or\_doi:thedoinumber in its place. The quarto-utils code searches for _doi: or\_doi: and parses for the DOI. The DOI can take the form of just the number (such as 10.48550/arXiv.1003.6087) or the full uniform resource locator (URL; such as https://doi.org/10.48550/arXiv.1003.6087). If invalid DOI codes are provided, quarto-utils will report that it was not able to find a reference for a given string and will leave the .qmd file unchanged. This feature is another method to streamline the writing process. Many bibliographic database software programs exist, but authors may find it more efficient to simply search the internet for a reference they want to cite, copy the DOI, paste it into their .qmd file, and keep writing. The BibTeX file generated by quarto-utils may require manual formatting, and occasionally, automatically generated outputs prevent Quarto from rendering files until special characters (such as non-American Standard Code for Information Interchange [ASCII]) are removed. Also, citations listed on doi.org may be incorrect and sometimes require additional curation and formatting.

Script-based writing programs such as Quarto offer advantages compared with traditional word processing programs by allowing writers to focus on writing rather than formatting (Baumer and Udwin 2015). For example, scientists can readily change formatting if they need to change reports (such as completion reports or partner summaries) to journal articles or change formatting across journal articles because only style files need to be changed rather than reformatting the entire document. Additionally, reports that are completed and rerun on a regular basis can be formatted to automatically include numbers in the text to avoid tedious and error-prone copying and pasting of values such as the examples previously shown in this document where numbers are reinserted each time the source file is recompiled. When integrated with statistical and analytical programming languages such as Python or R and publicly released, files created by these programs also more readily support FAIR principles because the details (and code) necessary to recreate results are embedded within the Quarto document. The FAIR principles are increasingly being used by science agencies for conducting and documenting research and monitoring programs. For example, the U.S. Geological Survey includes FAIR principles as part of their road map for science (Lightsom et al. 2022) and U.S. Fish and Wildlife Service planning documents also includes FAIR principles (U.S. Fish and Wildlife Service 2023b).

Thus, we created an example of how to prepare manuscripts in a Quarto document for following the style guide for the Journal of Fish and Wildlife Management. Our example could readily be adapted for other journals with similar Word-based workflows such as Environmental Toxicology and Chemistry or the Journal of Wildlife Management. The Quarto workflow can also serve as a front end to journals using LaTeX-based workflow. Aside from directly helping authors who write journal articles or other products such as annual reports, we also hope our publication will raise awareness for fish and wildlife managers about this tool. For example, many reports that are published weekly, monthly, quarterly, annually, or on a similar interval would benefit from not only using a computer script to perform the statistical analysis, data formatting, plotting, or other number crunching but also in preparing the document itself. The example described in this paper and fully provided in Erickson et al. (2024) could also serve as a starting place for these documents.

Please note: The Journal of Fish and Wildlife Management is not responsible for the content or functionality of any supplemental material. Queries should be directed to the corresponding author for the article.

Reference S1. Lightsom FL, Hutchison VB, Bishop B, Debrewer LM, Govoni DL, Latysh N, Stall S. 2022. Opportunities to improve alignment with the FAIR principles for U.S. Geological Survey data. U.S. Geological Survey Open File Report 2022-1043. Reston, Virginia: U.S. Geological Survey.

Available: https://doi.org/10.3133/ofr20221043 (1036 KB)

Reference S2.U.S. Fish and Wildlife Service. 2023a. Budget justifications and performance information fiscal year 2024. Washington, D.C.: U.S. Department of the Interior.

Available: https://www.fws.gov/media/fiscal-year-2024-fish-and-wildlife-service-budget-justification (5754 KB)

Reference S3.U.S. Fish and Wildlife Service. 2023b. Waterfowl population status, 2023. Washington, D.C.: U.S. Department of the Interior.

Available: https://www.fws.gov/media/waterfowl-population-status-2023 (19894 KB)

We thank all reviewers and editors, both the journal’s and internal U.S. Geological Survey, for their feedback that improved this manuscript. We thank the U.S. Geological Survey Biological Threats and Invasive Species Research Program and U.S. Geological Survey Water Resources HyTest Project for funding.