3. Tips and Comments

Some Personal Experiences from Using Quarto (or R Markdown)

  • Do not get frustrated when Quarto does not get you all the way to the final result that you want! Tinkering with layout options often takes a lot of time and is not always worth the effort. The most important reason for academics to use Quarto is usually to ensure the reproducibility of your analysis. For everything else, do not feel too bad when using some of the following workarounds:

    • Render your document to .tex or .docx and do some manual formatting required by academic journals.
    • Instead of forcing all your (very) senior collaborators to learn Quarto, just give them the rendered .pdf or .docx and incorporate their comments into the Quarto document yourself.

  • Make sure that your project still renders without problems as often as possible:

    • Frequently use the Render button when working on your Quarto documents, to ensure that you have not made a mistake. Debugging Quarto documents is very hard when you cannot say for sure which section in your code introduced an error that prevents rendering. Never leave a Quarto project at the end of your workday that does not render correctly! Trust us, just don’t do it!
    • We highly recommend to always use Quarto together with version control. For an introduction on how to use git within RStudio you can use this tutorial. Using version control is even more important when you want to collaborate with your colleagues.

  • When using Quarto together with version control (as recommended!), it can be very useful to place each sentence in your .qmd document on a separate line. This makes it much easier to follow changes (e.g. fixing a small typo in a manuscript), because git will always highlight the whole line in which changes have been made.

  • Be careful if you use the cache feature that we recommended to initially skip in the second tutorial. Although caching is powerful and can be very useful, it can lead to unexpected and invisible problems with respect to reproducibility. We recommend that you do not use the cache by default and that you carefully read this thoughtful chapter before using the cache in any of your own projects.

  • We recommend that you do not rely on the visual mode in RStudio too much: Even if you like the Visual Editor, make sure that you also gradually learn how do do everything in the raw source mode. When learning how to use Quarto, using the visual mode and then switching to source mode to see the result can be very useful.

  • Make it a habit to specify the language of a document in the YAML header (e.g. lang: de for German). Hyphenation, for example, relies on having the correct language set.

Optional settings to the visual editor in RStudio

The Quarto tutorials use the Visual Editor in RStudio. If you followed the tutorial as intended, this should have helped you to make up your mind on whether you like this mode when working with Quarto. If you have come to the conclusion that you want to keep using the Visual Editor, we recommend to read this page and have a look at the following RStudio settings:

  • In RStudio go to Tools > Global Options > R Markdown > Visual
  • Choose the options:
    • Show margin column indicator in code blocks
      • Default spacing between list items: spaced
      • Automatic text wrapping (line breaks): sentence

Conclusion

Before we conclude the workshop, we want to point you towards our advanced exercises you might be interested in after you have completed the beginner tutorials, as well as a collection of links with our most recommended Quarto resources.

We wish you all the best on your future Quarto journeys! πŸ₯³ πŸ‘ πŸŽ‰