2. Creating our content with Quarto

Now that we know how to make use of GitHub and Visual Studio Code, we are going to use Quarto to create our website 🎨 !

Quarto is a static website generator. It is a software that allows us to create web content from human readable files.

Usually, we should learn HTML and CSS, and JavaScript to know a bit of Web development. Indeed, those are the languages that traditional web browsers support. When we go to a webpage, our web browser transforms html and css into a graphical interface, which is easier to understand for humans. Javascript allows us to implement interactive features. However, in recent years, a lot of static website generators have emerged, making the creation of websites much easier. Among them, Jekyll, Zola, Hugo, and Quarto can be cited, but they are far from being the only ones available.

This tutorial focuses on Quarto for several reasons. First, it is easy to use. The commands are user-friendly, and do not require much background knowledge. Second, its file format (qmd, or “quarto markdown”) allows to easily include data visualization, code and support some very useful libraries like Shiny, that allow to create interactive web pages with data. It makes it easy to showcase our work if we deal with data and statistical analysis with R, Python, or Julia. It is therefore especially interesting if we are trying to build a research portfolio 😎.

By the way, this webpage was done with Quarto.

Installation of Quarto

The first step of this chapter is to download Quarto here.

Figure 2.1 : Installation page of Quarto

Figure 2.1 : Installation page of Quarto

Once it is done, we will be able to interact with Quarto through the terminal of vscode.

Create a Quarto project

Now that Quarto is installed, we can create a Quarto project in our folder (the one we synchronized with our online GitHub repository). In order to do that, we go back to vscode, and enter quarto create in the terminal of our open folder.

Figure 2.2 : Creation of a project with Quarto

Figure 2.2 : Creation of a project with Quarto

After entering quarto create, Quarto asks us different things :

  1. The nature of the Quarto environment we want to create. We have the choice between a project and an extension. We are going to choose project.
  2. The type of our project. It gives us the choice between :
    • default
    • website
    • blog
    • manuscript
    • book
    • confluence
    We could choose several options here. For example, default would work well enough also. However, let’s stick to website for the sake of simplicity.
  3. Quarto then asks for the Directory we wish to create our Quarto project in. Since we are already in the folder we opened with vscode, we should write a simple dot . and press enter.

The dot . refers to the current directory in several langages. To understand better how a path works, we can consult this article.

Once the creation process is done, we will see appear in our folder several files : index.qmd, about.qmd, _quarto.yml, style.css.

Let us take a moment to comment on what they do :

  1. The files with a “.css” extension are Cascading Style Sheets (css) files. Together with HTML, CSS is one of the main languages for web development. Those kind of files are mainly responsisble for the appearance and design of websites. It is not necessary to modify them for the purpose of this tutorial, but we can inform ourselves about it on this page.
  2. The files with a “.qmd” extension are Quarto files. This extension stands for Quarto MarkDown (qmd). They correspond to what the future pages of our website will be. They support various langages, like traditional Markdown, \(\LaTeX\), and more… We will change our portfolio pages by modifying these pages.
  3. The files with a “.yml” extension are configuration files. We use them to set some rules that Quarto will apply to generate our pages. For example, we will modify the navigation bar (or navbar) through these files.

The preview and render commands

Quarto allows us to create a properly designed website by only interacting with basic qmd files. We need however to see what results they yield.

To see the graphical result of our qmd files, we need to use two main commands : the quarto preview and quarto render commands.

The quarto preview command allows to see in real time what our qmd and yml yield. After entering it in the terminal console, it automatically opens a page on our default browser where we can see the graphical results of the latest saved version of our files. If there is an error with our files (for example a bad configuration within our yaml file), we will not be able to see correctly the results, and an error message will pop-up. We usually use it at the beginning of a work session, when we bring change to our portfolio.

The quarto render command allows to create html and css files from our qmd and yml files. We usually use it at the end of a work session, when we are satisfied with the changes we brought to the our website. Essentially, it does the same as the preview command, without opening a browser to see our changes in real time.

Let’s try to run the quarto preview command :

Figure 2.3 : Running the quarto preview command on the vscode terminal.

Figure 2.3 : Running the quarto preview command on the vscode terminal.

We should briefly see some blue text “preparing to preview”, followed by the names of our qmd files, before our default browser automatically launches itself.

If we did not modify the basic files, we should see something like this on our web browser :

Figure 2.4 : The graphical result of an empty quarto project.

Figure 2.4 : The graphical result of an empty quarto project.

Okay, we have our first graphical results ! What happened exactly here ? First, we entered quarto preview. Quarto first transformed all our qmd files in our folder in readable files for our web browser, i.e. html and css files. Then, it opened those html and css files with our default browser. What we are seeing is the result of this conversion from qmd to html and css.

We can notice that the URL of our page looks a bit different than the websites we usually access. Indeed, we should have something like “http://localhost:6986/”, or any other kind of four numbers combination. This is because Quarto is currently watching at our file, and will refresh the page as soon as any of our qmd or yaml files are changed and saved. Simplyt put, “localhost” means that it is our computer, and the four numbers are the port of our computer quarto is using to display the files.

Now, our terminal is busy reading our files in the web browser. We can create a new terminal session by clicking on the “+” in vscode. To stop the process, we can click on our terminal and then enter ctrl+c (command+c for MacOS keyboards).

How to modify our content

Now that we rendered the first version of our page, how do we modify its content ?

If we want to modify the homepage of our website, we can go to the index.qmd file, and change directly the text. By default, Quarto should have filled the document with :

---
title: "Home"
---

This is a Quarto website.

To learn more about Quarto websites visit <https://quarto.org/docs/websites>.

That yields the previous image.

We can modify it by writting for example :

---
title: "Home"
---

Hello, I am Paulo Gugelmo, currently a first year
student of the Master of Research in Economics at Sciences Po. 
My research interests are environmental economics. 

Feel free to reach out to me at my email adress :
"paulo.gugelmocavalheirodias" followed by "@sciencespo.fr" !

This should yield :

Figure 2.5 : Basic index page.

Figure 2.5 : Basic index page.

We should usually avoid putting our entire email adress directly in our webpage. Some bots are constantly scrapping webpages to get potential email adress that are later on the target of spam or fraudulous emails.

As we see, the changes are pretty straightforward. Since qmd files are basically a form of markdown file, we can use the markdown syntax for our content.

If you are not familiar with the markdown syntax, it is easy to understand. I encourage you to go check some documentation.

For plain text, note that we can enter jumplines without actually rendering a jumpline. If we want to do a breakline, we should let at least one empty line between two text chunks.

We are now going to cover some features of markdown.

Titles and subtitles

If we write plain text in our qmd file, we will get normal text in our page. However, if we want to have titles and subtitles, we can use the # sign before it.

In this way, one # will yiel a title, two # a subtitle, etc., until the sixth level. With text filler, we could write the following code :

---
title: "Home"
---

Hello, I am Paulo Gugelmo, currently a first year student of
the Master of Research in Economics at Sciences Po. 
My research interests are environmental economics. 

Feel free to reach out to me at my email adress : "paulo.gugelmocavalheirodias"
followed by "@sciencespo.fr" !

# Title 

Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris 
nisi ut aliquip ex ea commodo consequat.

## A Subtitle 

Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris 
nisi ut aliquip ex ea commodo consequat.

### A subsubtitle 

Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris 
nisi ut aliquip ex ea commodo consequat.

This would then yield :

Figure 2.6 : Example of titles and subtitles.

Figure 2.6 : Example of titles and subtitles.

It is as simple as that, and by default, Quarto creates a table of content automatically for us in the right-side of our page !

Adding documents and pictures

Now, we could also want to include some pictures in our text. For example, some pdf of a long article we wrote or screeenshots.

In order to do so, we are going to use the ![Figure 2 : description](link) markdown syntax.

In the previous example, we had url as links, that could be accessed on internet. Now, let’s imagine that we have a pdf file in our computer that we want to share on our portfolio. Usually, such a pdf is not available online on a public url.

The first step we want to do is put the files we want to share in our folder in vscode. We should have something like that :

Figure 2.8 : A vscode folder with files that we want to share.

Figure 2.8 : A vscode folder with files that we want to share.

Note that in the left side of my screen, in the explorer bar, I now have to additional files : “screenshot.png” and “2_8_markdown_guide.pdf”.

If we want to include them, we could write :

---
title: "Home"
---

Hello, I am Paulo Gugelmo, currently a first year student
of the
[Master of Research in Economics](https://www.sciencespo.fr/ecole-recherche/en/academics/masters/master-economics/)
at [Sciences Po](https://www.sciencespo.fr/en/). 
My research interests are environmental economics and open source !

Here is an interesting website :

![Figure 2.9 : A screenshot of the CRAN website.](screenshot.png)

Here is an interesting guide : 

![Figure 2.10 : This is the Markdown guide, written by Matt Cone.](2_8_markdown_guide.pdf)

Feel free to reach out to me at my email adress :
"paulo.gugelmocavalheirodias" followed by "@sciencespo.fr" !

This code would yield :

Figure 2.11 : An attempt to include pictures and pdf

Figure 2.11 : An attempt to include pictures and pdf

We see that the picture, a screenshot of the CRAN website, seems to work fine. However, the markdown guide, written by Matt Cone, and available here, is displayed in a smaller dimension than the page. This is due to the fact that we are trying to include a pdf as a picture. To include a pdf, we can thus use the normal link syntax, while directing to the emplacement of our pdf file. In this way, a syntax similar to You can read the markdown guide of Matt Conen [by clicking on this link](2_8_markdown_guide.pdf) would work better. We could thus write :

---
title: "Home"
---

Hello, I am Paulo Gugelmo, currently a first year student
of the
[Master of Research in Economics](https://www.sciencespo.fr/ecole-recherche/en/academics/masters/master-economics/)
at [Sciences Po](https://www.sciencespo.fr/en/). 
My research interests are environmental economics and open source !

Here is an interesting website :

![Figure 2.12 : A screenshot of the CRAN website.](screenshot.png)

You can read the markdown guide of Matt Conen [by clicking on this link](2_8_markdown_guide.pdf)

Feel free to reach out to me at my email adress :
"paulo.gugelmocavalheirodias" followed by "@sciencespo.fr" !

That would yield :

Figure 2.13 : Including a pdf document through a local link.

Figure 2.13 : Including a pdf document through a local link.

And if we click on the link, we are redirected to the pdf file within our browser.

For the case of a portfolio, we could for example include our CV in this fashion.

Adding code

Now, we might want to include code snippets in our portfolio. For example, we have a project for which we wrote in R or any other languages, and we want to make the code easily accessible by our visitors.

In order for us to do that, we have two options. Either we want to include code inline, in which way we write our code between those reversed ticks (or “backticks”) : ``, or we want to include a code snippet, that has several lines, in which case we write three reversed ticks at the beginning and at the end of our code like this :

```{r}
print("Hello world !")
```

The code will yield :

print("Hello world !")
[1] "Hello world !"

We are here touching one of the biggest strengths of Quarto. Despite being a “simple” static website generator, it allows us to include and execute code in our page. This can be very useful to display work that requires data treatment and/or other statistical computations.

For example, the following code in R :

```{r}
data(iris) # load the freely accessible dataset named "iris"
summary(iris) # display a simple statistical summary of this dataset
model = lm(iris$Sepal.Length ~ iris$Petal.Length)
# create a linear model trying to explain the sepal length by the petal length

plot(x = iris$Petal.Length,
  y = iris$Sepal.Length, 
  xlab = "Petal Length",
  ylab = "Sepal Length") # plot those two variables
abline(model) # draw the linear regression line on the plot
```

Will generate :

data(iris) # load the freely accessible dataset named "iris"
summary(iris) # display a simple statistical summary of this dataset
  Sepal.Length    Sepal.Width     Petal.Length    Petal.Width   
 Min.   :4.300   Min.   :2.000   Min.   :1.000   Min.   :0.100  
 1st Qu.:5.100   1st Qu.:2.800   1st Qu.:1.600   1st Qu.:0.300  
 Median :5.800   Median :3.000   Median :4.350   Median :1.300  
 Mean   :5.843   Mean   :3.057   Mean   :3.758   Mean   :1.199  
 3rd Qu.:6.400   3rd Qu.:3.300   3rd Qu.:5.100   3rd Qu.:1.800  
 Max.   :7.900   Max.   :4.400   Max.   :6.900   Max.   :2.500  
       Species  
 setosa    :50  
 versicolor:50  
 virginica :50  
                
                
                
model = lm(iris$Sepal.Length ~ iris$Petal.Length)
# create a linear model trying to explain the sepal length by the petal length

plot(x = iris$Petal.Length,
  y = iris$Sepal.Length, 
  xlab = "Petal Length",
  ylab = "Sepal Length") # plot those two variables
abline(model) # draw the linear regression line on the plot

If you don’t use R, don’t worry, Quarto also support several other languages, such as Python, Julia, and Observable JavaScript. In theory, if you know how to deal with code engine, you can also run other languages on Quarto.

Adding math

Finally, it’s also possible to add some math to our website. Indeed, markdown supports \(\LaTeX\), and we can simply include our \(\LaTeX\) code between dollar signs $ some math $ to generate inline math, or between two dollar signs $$ an equation $$ to generate math blocks.

For example, the following code :

The arithmetic mean $\bar{x}$ is defined as : 

$$
\bar{x}=\frac{1}{N}\sum_{i=1}^{N}x_{i}
$$

will produce :

The arithmetic mean \(\bar{x}\) is defined as :

\[ \bar{x}=\frac{1}{N}\sum_{i=1}^{N}x_{i} \]

If you are not familiar with \(\LaTeX\) and will be in positions where you have to write documents with math in it, I highly recommend you familiarizing yourself with this language. The Overleaf website is a good place to start, and this guide here is very complete.

How to modify the navigation bar

Now that we are more proefficient in the generation of content, we can talk about the aspect of our portfolio. Without being website designers, we can recognize that an essential element of any website is the navigation bar. In Quarto, it is automatically displayed in all our pages, and we can only modify it in our _quarto.yml file. By default, we should have something similar to this :

project:
  type: website

website:
  title: "."
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true

That yields a navbar like :

Figure 2.14 : The default navbar of Quarto

Figure 2.14 : The default navbar of Quarto

In this example, the content of the navigation bar, or “navbar”, are determined by all elements following the navbar element in the website list. Here, we see that it has two elements : the homepage, defined as the index.qmd file, and the about page, defined as the about.qmd file.

Normally, the title of our page should appear in our browser, despite not being specified in our navbar. This is the default setting of Quarto. To unable this option, we can add title: false in our navbar list :

website:
  title: "."
  navbar:
    title: false
    left:
      - href: index.qmd
        text: Home
      - about.qmd

This should yield :

Figure 2.15 : A navbar without title.

Figure 2.15 : A navbar without title.

We may however want to keep it. in this case, it should be better to modify the title of our webpage to a customed one, like our name. For example, in my case :

website:
  title: "Paulo Gugelmo Cavalheiro Dias"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

Now, to add a new page to our navbar, we can add an element in the left or right list such as :

website:
  title: "Paulo Gugelmo Cavalheiro Dias"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - projects.qmd
      - about.qmd

For this configuration to work, we must first create a projects.qmd file beforehand in our folder. This will then implement a new link in the navbar, displayed in its left part, having for name the title of the file, i.e. here Projects :

---
title: "Projects"
--- 

Welcome to my projects webpage. You will find here a list of ongoing or past projects I worked on.

If we now combine the two mentioned code, we should have something like :

Figure 2.16 : Our vscode interface.

Figure 2.16 : Our vscode interface.

Figure 2.17 : The graphical result.

Figure 2.17 : The graphical result.

Adding a new document to the navbar

Output directory

A final important point for the publication of our website in the last chapter is the out-put directory.

In order for us to configure the output directory, we are going to change our _quarto.yml file to add the output-dir line :

project:
  type: website
  output-dir: docs

This line tells Quarto to create a subdirectory called “docs” to store the html and css files. It is important to specify this so that GitHub Pages recognize more easily our files to publish them.

Therefore, make sure to add this line, run quarto render, and check that the “docs” directory is created in the folder.

Further resources

At this point, we roughly covered the basics of Quarto. Although not complete, our portfolio is functional. If we wish to dive further into the personalization of our website (which is probably the case), we can spend more time reading their documentation.

Quarto is a very powerful tool. We can use it to quickly produce content and maintain it with the presented workflow in this tutorial. I highly recommend the reading of their documentation here, and more specifically to follow through their Get Started guide.

Back to top