Exercise: Create a Quarto Manuscripts website for one of your own scientific publications
Description
In this unstructured exercise we would encourage you to
- convert one of your own manuscripts into Quarto
- use Quarto Manuscripts to create a website for this publication
- publish this website with Github Pages
The final result of the exercise could be a Quarto Manuscript website which serves as a hub containing everything necessary to reproduce your manuscript.
For this exercise, we do not provide step-by-step instructions. Instead we link to the relevant Quarto Manuscript documentation, provide an example of how the final result of the exercise could look like, and list the most important steps when converting a Quarto document into a Quarto Manuscripts website.
What are Quarto Manuscripts?
The Quarto documentation on manuscripts reads:
Instructions
We suggest that, before you start with your own Quarto manuscript, you have a look at the Getting Started tutorial on how to create a Quarto Manuscript website.
Additional documentation on Quarto Manuscripts can be found here.
Final result
The final result of the exercise could look something like this:
Steps to convert a Quarto document into a Quarto Manuscripts project
If you already have written your manuscript with Quarto, there are only a small number of steps necessary to convert your document into a Quarto Manuscripts website. Without guarantee of completeness, the most important steps are:
Create the file
_quarto.yml
in your RStudio project. A good starting point for the content of this file is:project: type: manuscript manuscript: article: index.qmd format: html: comments: hypothesis: false pdf: default docx: default jats: default execute: freeze: auto
The main
.qmd
document containing your manuscript must be namedindex.qmd
by default. If you want to use another name, adjust the linearticle: index.qmd
in the file_quarto.yml
.Make sure that you remove unnecessary (or conflicting) YAML options in your article and additional notebook
.qmd
files. We suggest to only use a minimum of options first, test that everything works and then add further options when needed.Quarto Manuscripts supports many useful YAML options that can be used in your
index.qmd
file. We suggest that you have a look on the Quarto documentation on scholarly writing this and consecutive pages.If your project contains computations that take a long time to run, we suggest you make sure you understand how the freeze functionality of Quarto works by reading this and this.
Optional: If you need to format your manuscript in APA style, you might want that 1) your Quarto Manuscripts website uses standard HTML themes and formatting but uses APA citation style, 2) your downloadable
.pdf
file is nicely formatted as a APA journal article that you can upload to the preprint server of your choice, and 3) your downloadable manuscript in.docx
format is formatted as a APA manuscript, which is how many APA journals require manuscripts to be sent into peer review.You can achieve this by
downloading the apa-quarto extension as explained in the previous exercise
using the following code in your
_quarto.yml
file:format: html: default jats: default apaquarto-pdf: documentmode: jou a4paper: true pdf-engine: lualatex keep-tex: false apaquarto-docx: default
using the YAML option
csl: apa.csl
in the fileindex.qmd
(the fileapa.csl
can be downloaded here)