Website Tutorial using R, Quarto and Gitlab Pages

Share data, code and dynamic reports in an easy-to-build website

A very easy set up of a free website where you can share your dynamic reports or other research outputs

Why is this useful?

Sharing documents, code, data and outputs with collaborators or to a broader audience is an essential step towards a good scientific practice. A website that can be managed by researchers themselves seems the ideal platform for efficient sharing. If this depends on IT support for maintenance it will not be practical for routine use, but learning web-development imposes an unnecessary and unacceptable burden to a scientist’s already heavy workload.

Here we describe an approach that uses free, open-source tools which are also widely-used for analytic purposes (e.g., data handling, statistics and visualizations). Thus, the requirements for learning web-specific tools is minimal. Importantly, this approach can be integrated in a research group’s routines to compile dynamic reports with documentation, code, analysis and outputs in a single-document. This makes each step easier to understand, facilitates troubleshooting and improves computational reproducibility see CRS primer

Software required

All these tools are free and open source

• R: a widely-used software environment for statistical computing and graphics

• Rstudio: an interactive development environment to use for working with R. It includes a visual editor and essential features to facilitate code editing.Importantly it supports Quarto (see below)

• Quarto: it is multi-language tool to facilitate technical and scientific publishing. It is supported by Rstudio. In the quarto documents we will have text chunks (plain text with markdown syntax, see note below) and code chunks (written in R, but it can also be other languages). This is an evolution of Rmarkdown with more functions, output options and more better interoperability between languages and environments. For the user, working with Quarto and Rmarkdown is quite similar, with some minor differences in syntax

Dictionary

Some terms that often pop up if you search for documentation on the tools above:

• IDE: interactive development environment, this is an application that help us develop code more efficiently. They have features like syntax highlighting, intelligent code completion, debugging tools, etc.

• Markdown: it is a markup language, that is, a set of symbols inserted in a text document to control structure, formatting and how its parts relate to each other. Markdown syntax is very simple and easy for humans to read. It allows us to write stuff in plain-text in a way that can be transformed into formatted text by other tools.

• Pandoc: this is a program integrated in R studio that renders markdown text into other output formats like pdf, html word , etc)

• Knitr: this is the engine that executes the code chunks in a Quarto or Rmarkdown document. It can be installed as a package in R

• yaml or yml: YAML is a human-readable language used for configuration files. Here we use a .yml file to configure our site and a yml header to add settings and metadata on top of each quarto file

Files required

At least you will need the following:

• A _quarto.yml configuration file (required filename & extension)

• An index.qmd quarto markdown (suggested filename)

Step-by-step videos

Assuming you have installed RStudio and quarto

1. Make a website from scratch in 5 minutes

This 5 minutes video shows how easy it is to create the basic skeleton of the website.

Step 1. Make a new folder for your website

Inside the folder you will have the _quarto.yml file at the top level, then you can organize the quarto markdown files with the content in subfolders if you want.

Step 2. Create a _quarto.yml file with some settings

They are given in plain text. Indentation counts. There are many examples online which would require minimal adjustments. A very simple example:

project:
    type: website
    
website:
    navbar:
        title: Home
        
format: 
    html:
        author: Center for Reproducible Science

“navbar” indicates a navigation bar on top of the website, but you can also define a “sidebar”. In there you can refer to the different pages that will make up your site. In this example we just make an skeleton with the home page.

Step 3. Create a quarto file and open it in R studio

We recommend creating an R project file in Rstudio to point at your web’s folder and open your quarto files with that project open in Rstudio to avoid having future problems finding the path to your files.

You can write plain text with markdown syntax on it and use a yml header delimited by --- symbols to add metadata or settings

Step 4. Click ‘render’ or type quarto::quarto_render() in Rstudio

That’s it. A new subfolder named _site will be created with a file index.html which is your website

2. Add pages to your website

Now we can just populate the pages by:

• Adding .qmd files with content. A recommended organization is a page per folder. If a page will contain many subpages, you can set up a main file in that folder (e.g., index.qmd) with a yml header (delimited by ---) using the listing option. This will automatically include all .qmd files without having the need to specifying the _quarto.yml file.

• Adapting the _quarto.yml file to indicate which pages and where you want to show them (e.g., in a navigation bar on top, right or left or in a sidebar)

• Click ‘render’ or type quarto::quarto_render() in Rstudio

An example of a folder structure of the website before rendering:

website
│
├── index.qmd               # (REQUIRED) Contents of home page 
├── _quarto.yml             # (REQUIRED) Quarto project configurations 
│
├── Project.Rproj           # Recommended when working with R studio 
│
└── contents                # (suggested name) Contents of each page
   ├── Page1                # Each page has a folder  
   |   └──  index.qmd       # A page can be just one qmd
   └── Page2                 
       ├──  index.qmd       # We can set a page to list all other .qmds in folder     
       └──  section1.qmd      

The following 5.5 minutes video shows a quick example. Read the subtitles for details.

3. Host it for free using Gitlab pages

(…) First activate gitlab pages, then move the content to ‘public’ folder (…)