Tutorial: Authoring

Some comments before the tutorial

The tutorial uses the Visual Editor in RStudio. We recommend to frequently switch between Visual and Source mode during the tutorial to see how the raw markdown syntax looks like.
Remember to put all .qmd files you download during the tutorial into the RStudio project directory you have created earlier.
We recommend to skip the Publishing section of the tutorial for now.

Start the tutorial

If you have problems during the tutorial come back here and see the next section for our list of anticipated issues. After completing the third tutorial, come back here and continue with our personal tips and comments on using Quarto on this page.

Let’s start

Now you can start the third tutorial at https://quarto.org/docs/get-started/authoring/rstudio.html.

Possible problems and related comments

The tutorial claims that creating a new .qmd document through the RStudio menu will create an empty document, which is not always true.
The tutorial claims that “the format choice (HTML) is not even reflected in the YAML as it is the default output format for Quarto documents” when creating a new .qmd document, which is not true.
The tutorial does not talk about where to save the .qmd file. For our case, it is most practical to save it in the project folder you have created for the Quarto workshop.
The tutorial does not mention that the Render on Save option in RStudio is document specific and must again be ticked for the new .qmd file if you want to use it as showcased in the tutorial.
When you render the .qmd file as .docx by use of the Render button in RStudio for the first time, RStudio might (misleadingly) ask where to safe the file, even though the .docx file has already been silently created in the background (because the yaml header specifies that all formats should be created on rendering).
When you have used the Render button in RStudio to render .docx this might break the Viewer in RStudio (because RStudio seems to remember the last output format it has rendered and the Viewer does not work for .docx). One solution to fix this is to manually render once as .html or .pdf via the Render options, which should reactivate the Viewer.
The tutorial wants you to add a reference to the equation labeled #eq-slr, but this reference is actually already included in the .qmd file.
In the section on Cross References, the tutorial could make it more clear that cross-references must use the reserved keywords (fig-, tbl-, eq-, …) in the respective labels. This means that when you want to reference a figure with the @ syntax, the label for the R chunk that produces that figure must begin with the reserved keyword fig- (e.g. #| label: fig-myfigure). Similarly, the label for a chunk that produces a table must begin with tbl- and so on. For more details, check the cross-referencing documentation.
Rendering the final authoring-complete.qmd file you can download at the end of the tutorial will only work, if you also have the references.bib file in the same folder. This file was created automatically by RStudio when you inserted your first reference in the citations section of the tutorial. The created bibliography file should look like this:

When the .bib file is present, rendering authoring-complete.qmd should produce the following three output files (we have added embed-resources: true to the html options in the YAML header to produce a standalone html file that can be shared with others):