Writing Manuscripts
Everyone knows that managing the drafting, feedback and submission of manuscripts is a lot of work. Some colleagues require .docx format to allow for track changes, some work with LaTeX. Journals each have their own arcane formatting requirements, which are rarely corrected documented in their own author guides…
Using Quarto for manuscripts is not a silver bullet for all these problems but it does reduce a lot of the headaches by keeping narrative text, citations, figures, tables (generated by code or imported) in a single reproducible workflow.
Start with a good directory structure: figures, data, scripts, and supplemental materials. This keeps everything organized and makes it easier to manage the different components of your project.
my-manuscript/
├── manuscript.qmd # main document
├── references.bib # bibliography
├── figures/
│ ├── fig1.png
│ └── fig2.png
├── data/
│ ├── raw/
│ └── processed/
├── scripts/
│ ├── analysis.R
│ └── figures.R
└── supplemental/
└── supplemental.qmdKey benefits of using Quarto for manuscripts
Multi-Format Output
Leverage Quarto’s ability to render to multiple formats from the same source file to fufill different format needs:
.htmlor.docxfor internal review and sharing with collaborators..pdfand.tex(LaTeX) for journal submission.
There are quite a number of journal templates available for Quarto that can be used to format your manuscript according to specific journal requirements. But equally using journals LaTeX submission portal is often the easiest approach.
A major benefit for PhD researchers doing cumulative theses is if you write each of your papers with Quarto it is easier to combine them into a thesis. In fact one of the authors of this workshop prepared a template for doing this.
Reproducible Figures and Tables
When analysis is embedded, manuscript results become easier to update and verify. By setting up a custom ggplot or matplotlib theme in a separate script, you can ensure that all your figures have a consistent style and easily change colours or fonts according to journal requirements without having to manually edit each figure. This also makes it easier to maintain a consistent visual identity across all your publications.
Long code chunks in manuscript qmds for figures can be cumbersome, better to separate out into a script and source it in the header the manuscript. For example, you can have a figures.R script that generates all your figures and saves them to the figures/ directory. Then in your manuscript.qmd, you can source this script in the YAML header or at the beginning of the document to ensure all figures are re-generated before rendering.
Inline statistics from data
Quarto’s in-line code chunks allow you to pull values directly from your data, for example, p-values or summary statistics, ensuring that your manuscript always reflects the most current results without manual updates.
TODO Insert in line code chunk example here, e.g. “The mean pollinator diversity was r mean(diversity) across all sites.”
Integrated citation support
Integration with Zotero to keep citations in the same workflow as writing. In the visual editor you can also add a citation directly from the DOI
When you add a citation using the @ syntax Quarto automatically adds it to the bibliography (.bib) file and then upon rednering applies the citation style you have specified in the YAML header. This means you can easily switch between different citation styles (e.g., APA, MLA, Chicago) without having to manually reformat your references.
Cross-referencing
Quarto supports hypewrlinked cross-referencing of figures, tables, and sections to keep everything aligned as the manuscript evolves.
Supplementary Material Management
Supplementary material, including code for reproducing analyses, can be kept in the same project and linked to the main manuscript.