Updating the website

R
quarto
renv
Author

Nicklas Hafiz

Published

December 17, 2023

This website was created using Quarto. It is hosted on GitHub. In this chapter we will look at the underlying structure of this website, and how to update it.

Setup

  1. As the website is hosted on GitHub, you can just clone the repository.
  2. Open the RStudio project with RStudio.
  3. This website uses renv to keep the project specific package library up to date.

renv

Important

Make sure you’re using the R version recorded in the LOCK-file when working with renv. This makes things a bit easier. Of course, if the R version in the LOCK file is an old one, you can update it with renv::snapshot().

Wandering what renv is? Check out the renv Intro for more information.

The needed packages are recorded in the .lock-file, but not uploaded to GitHub. So the first thing you need to do is to install the necessary packages into your local project library:

# install.packages("renv")
renv::restore()

You can do this every time you start working on the website. Only packages that are not already in your project specific package library will be downloaded.

If your files need their own packages, just install them like you would normally do with either:

install.packages("eatGADS")
renv::install("eatGADS")

You need to do this even if you have them already installed on your PC locally, because renv uses a project specific library.

Important

Don’t forget to update the .lock file with renv::snapshot() if you have added new packages in your code. Otherwise the GitHub-Action will fail. But be concious about what is updated. If you are using an old version in the project, or old package versions, you might downgrade the projects package versions. So run renv::restore() before, to make sure your project library is up to date. renv will show you in the console what is updated from which version to which version.

File structure

Basically you just need to know where to put your files. Everything else will be taken care of by pushing to GitHub. Files can go into one of two folders: docs or posts. docs contains most of the tutorial files: They are structured into sub folders, like eatPackages or R. Here the quarto-files can be found that contain the actual website content. Edit them or add new ones. Make sure they are quarto-files with the .qmd ending.

_quarto.yml

On the highest directory level you can find the _quarto.yml file. It defines the structure of the website. If you want your new page to be displayed in the website navigation, you have to add it here. You can define different sections and give name the links to the websites:

    contents:
      - section: "R Tutorials"
        contents:
          - section: "Introduction"
            contents:
             - docs/R/index.qmd
             - href: https://nickhaf.github.io/r_tutorial/
               text: Selfpaced R Workshop
             - href: docs/R/ws1.qmd
               text: Einführung

This creates the section R Tutorials with the subsection Introduction. Introduction consists of three pages: the index.qmd page, which is like the main page of this section, the page Selfpaced R Workshop, which actually is only a link to another website, and the page Einführung, which links to the qmd-file ws1.qmd. Just add your pages where appropriate.

quarto-files

The quarto-files contain the actual content of the website. Just edit them like you would edit .qmd-files (or .rmd-files, as the rmarkdown syntax is quite similar). An introduction to the basic quarto functions can be found in the R SIG. Here are some additional useful tips:

Linking

You can easily link to other pages of this website, or to other websites:

[displayed text](link.de)

You might need to use relative paths: [renv](../r_sig/23_11_06_renv/index.qmd). This will link to the renv page in the posts directory.

Pictures

To add a picture to your website, save the picture in the same folder as your .qmd-file. Then you can display it with:

![](my_image.jpg)

1

Footnotes

You can add footnotes with:

Add a footnote[^2].

[^2]: My Footnote.

Add a footnote2.

Callouts

You can add little information boxes like this:

::: callout-tip
The R-SIG meets each every two weeks on Monday from 13:00 - 14:00.
:::
Tip

The R-SIG meets each every two weeks on Monday from 13:00 - 14:00.

There are multiple different options, take a look at the documentation for more.

CSS styles

You can tweak the appearence even more by using you own CSS-styles.

Editing on the web page

You can also find a small button called Edit this page next to the GitHub logo. This allows you to edit the page directly on GitHub.

Building the website

To get a preview of your website, click on the Render button in R Studio. Make sure you are not working locally and not on the network drive, because you might run into admin right problems otherwise. The rendering is not really necessary, because the website will only be built online when you push to GitHub. It will take a while (up to 20 min or more, depending on the size of the website) until the website is updated, as some checks are run first. The website will already get updated if you just open a pull request that wants to merge into main.

Further reading

The official documentation can be found here. A nice hands on tutorial on adding blog posts to an existing Quarto website can be found here, along with some additional tips on citations, footnotes etc.

Footnotes

  1. Image by Sinjin Thomas on Unsplash.↩︎

  2. My Footnote.↩︎