Content from A brief introduction to Quarto

Last updated on 2025-11-12 | Edit this page

Overview

Questions

  • What is Quarto and how can it be used to publish data?
  • What Options does Quarto give to customize your experience?

Objectives

  • Give an overview about Quarto and its features
Discussion

Discussion: What program or enviroment do you use for the creation and publishing of scientific papers?

What is Quarto?

There are many differnt environments used for the writing, editing and publishing of scientific papers and data. Ech offers a different emphasis on different features, quality of life improvments and backgrounds. The right tools and environment are essention for a clean and effective workflow. Quarto stands as an effective allrounder when it comes to the different stages and functionalities needed in the creatin of scientfic papers. Quarto is a free, open-source tool, made with the purpose of refining and improving the creation of technical and scientific documents. It utilized a plethora of integrated options, that create an environment where users can create multi-format documents, that can be easily converted between MSWord, HTML or LaTeX. The wide array of integrated functions, such as the implementation of code and visulizations, the easy convertability of documents and the integrated citation management system offer the user a concise and easy to understand working environment.

Callout

Core features of Quarto

Some of the core features discussed in this lesson are: + Creation of easily convertible .qmd files using Markdown and Pandoc + Multi-format display of data + Integration and display of code and illustrations in multiple coding languages + Built-in bibliography feature using automatic recognition and manual input

Content from Getting started

Last updated on 2026-01-05 | Edit this page

Overview

Questions

  • How do i open a new Quarto document?
  • What editing modes exist?
  • How do i switch between modes?

Objectives

  • Open a new Quarto document.
  • Create a working folder
  • Switch between editing modes

Choosing your working folder

In order to work in a clean and organized environment, we will first create a new working folder and choose to use it in Visual Studio Code. In order to do so, we will first open the options in the upper left corner of the window (depicted as three parallel horizontal lines). There we will follow the path of File -> Open Folder. Here we can then create a new folder, which we call “Art_distribution_paper”. Once selected, it will open the folder in VSCode and select it as our new working environment. All new documents, outputs and relevant data will be stored in this folder.

Opening a Quarto Document

Now we continue by creating our Quarto file. This is done by again selecting the options in upper left corner and following the path File -> New File. After installing the extension, two new options appear when creating a new file in VS Code: Quarto Document and Quarto Project. A Quarto Document creates a single file, that can be used to create singular Documents such as a PDF. A Quarto Project offers you the option to choose between several premade setups used to create more complex structures such as a blog, book or website.

As we are currently working on the very basics, we will choose the “Quarto Document” option when creating a new file.

After opening the new file, you should see the following:

The “empty” Documents only contain a small YAML header with generic information about title and format of the document.

By using the keybord shortcut Ctrl + S, we can now save our new Quarto document in our previously created “Art_distribution_paper” folder. We will call it “Moma_paper”

Visual and Source Mode

When working in a Quarto environment the user can decide if they wish to work in a visual or source code-based layout. The visual layout offers an easy to navigate environment similar to the layout of programs like MSWord. The Markdown specific code chunks are hidden as to not confuse the user. The source layout lacks the visual interface but includes the underlying markdown code of the document.

Neither of the two environments are inherently better then the other. We will be working with both the source and the visual layout of Quarto. You will be shown the correct ways of selecting the needed options in the visual interface and how to write the needed code in the source code of the document.

Callout

You can easily switch between the two editing modes by right clicking on your screen and selecting “Edit in Visual/Source Mode”. This will instantly switch you over. In this lesson we will continue to work with Source Mode.

Rendering Your document

To render your document and see its final look, you need to click the “Preview” Button on the top right side of the screen: Alternatively you can use Ctrl+Shift+K.

This will have two effects: 1. It will create a new file in your “Art_distribution_paper” folder, corresponding to your chosen format.

  1. It will split your screen and show you your preview on the right side of VSCode.
Discussion

Exercise:

Create a new folder called “Quarto_lesson” and open it in VSCode. Open a new Quarto document in VSCode and save it in your newly created folder.

Content from Markdown Basics

Last updated on 2026-01-05 | Edit this page

Overview

Questions

  • What is Markdown?
  • How do you use Markdown to write in Quarto?
  • What are the most common parts of Markdown syntax?

Objectives

  • Know the basic Markdown syntax.
  • Know how to write a simple text, containing a variety of Markdown syntax.

Markdown Syntax

In order to use the source mode of Quarto, one needs to be able to write a document using the Markdown programming language. The relative simplicity and straightforardness of Markdown makes it one of the ideal programming languages for beginners. It is used by a variety of programms and exists in the background of most modern text based programms. For example, this page is based on Markdown as well! Markdown is designed as a simple and easy to understand programming language. As such there are only a few key features the user needs to know to create basic syntax in Markdown.

These features contain some of the most common elements of written texts, such as tables, links and footnotes. But also features used to visually improve your text with features such as bold or italicised writing, horizontal lines for textseperation or differently sized headers. The implementation of picrtures is also possible to implement pictures in Markdown. Some of the most useful parts of Markdown syntax are shown here:

Writing our paper with Markdown

Now that we know some of the basic syntax of Markdown, we can start to write our paper!

Lets start with some headers to give our paper some structure. For this we start by creating a basic structure using the different tiers of headers offered by markdown:

# Introduction
## History of the MOMA
### Founding
### Recent History
## Overview of the Dataset
# The Distribution of Art
## Subsections of the MOMA
## Forms of Artworks
### Distinction by Material
### Distinction by Origin
## Analysis of the Dataset
### Summary of Data
### Visualisations
# Final Thoughts

This structure, created by the different quantity of # in each line, creates a tiered layering of headers, subheaders and so on. The more # we put at the start of a line, the less “important” a header is. This newly created structure will later be used by quarto to create the section headers, as well as a table of contents. You can put up t0 six # in a line.

Now that we have our section headers, we can add the most important part of a paper: the text. For this we can simple add whatever text we want to insert between our headers:

This could look like this:

# Introduction
## History of the MOMA
### Founding
The MoMA was founded in 1929 in New York City by a group of patrons, including Abby Aldrich Rockefeller. Its mission was to introduce the public to modern art and cultivate appreciation for contemporary creative expression. Early acquisitions focused on European avant-garde works, and the museum quickly became a hub for exhibitions, education, and innovation in the arts.
### Recent History
Over the decades, MoMA has expanded both physically and conceptually. Renovations, new wings, and acquisitions have diversified its collection, integrating photography, design, and media arts. Recent decades saw increased international representation and digital initiatives, reflecting global contemporary practices. Today, MoMA balances historic modernist works with experimental contemporary pieces, maintaining its role as a dynamic cultural institution.
## Overview of the Dataset

Low lets add a few more visual elements to our texts. We could use for example an image and a table to do so.

In order to add a an image we can use either images from the internet by adding a link, or add a path to the location of the image on the device. Images are marked by an exclamation point, square brackets, round brackets and winged brackets. The quare brackets can be left empty, but otherwise contain an alternate text for the image. The round brackets contain the link or datapath of the image, and the winged brackets can be used to change the rendred images size and dimensions. This could look something like this:

Using a link:
![](https://upload.wikimedia.org/wikipedia/commons/thumb/8/8b/MoMa_NY_USA_1.jpg/960px-MoMa_NY_USA_1.jpg){width=x height=300}

Using a local image. The image must be in the same folder as the Quarto document!
![](MOMAyard.JPG){width=x height=300}
Callout

If your images are not placed in the same folder as your Quarto document, you must place copy the complete path to the directory of your image into the brackets! For example :

![](C:\Users\user\Documents\Art_distribution_paper\images\introduction\MOMAyard.JPG){width=x height=300}

Now we can add a table to our document. For this we “draw” a table in Markdown like this:

## Subsections of the MOMA

| Name | Responcebility |
| -------- | ------- |
| Architecture and Design | Collect, manage, and exhibit architectural drawings and models, design objects, and graphic design works. |
| Drawings and Prints | Collect, manage, and exhibit modern and contemporary drawings and prints. |
| Film | Collect, manage, and exhibit film. The department consists of the following divisions: Film Archive, Film Study Center, Circulating Film Library, Exhibitions, and Programming. |
| Media and Performance | Collect, manage, and exhibit film. The department consists of the following divisions: Film Archive, Film Study Center, Circulating Film Library, Exhibitions, and Programming. |
| Painting and Sculpture | Collect, manage, and exhibit modern and contemporary painting and sculpture. |
| Photography | Collect, manage, and exhibit modern and contemporary photography |
| Publications | Produce and publish the Museum’s exhibition catalogues and other books, including digital publications. |
| Video (Digital Media) | Work with MoMA video producers to develop and produce content for MoMA’s YouTube Live series |

The different sections of the table are devided by |.

When we have now added our Table and Image to ourtext it Could look something like this when rendered:

Discussion

Exercise:

Use your newly aquired knowledge in Markdown to fill your still empty Quarto documents with text. Try to use a variety of features stuch as pictures or line breaks, be creative!

Caution

Some Help

Should you need some help with Markdown or want to deepen your understanding of this extremely usefull language, there are a plethora of websites aimed at helping newcomers learn all there is about Matkdown. Websites like MarkdownGuide offer a wide variety of guides, cheat sheets and help.

Content from An introduction to YAML headers

Last updated on 2026-02-18 | Edit this page

Overview

Questions

  • What is YAML?
  • How to use a YAML header?
  • What are the most useful Key-Value pairs for a scientific paper?

Objectives

  • Create a simple YAML header containing basic information.
  • Apply the correct Key-Value pairs for use in a scientific paper.
  • Implement a detailled YAML header for a scientific paper.

What is YAML

Many Quarto documents start with a so called YAML header. These headers contain fundamental information about the document and are used to concisely and easily configure metadata and appearance. While it is not necessary for the document to function, they are a useful way of integration metadata and appearance into your documents.

YAML(short for “YAML Ain’t Markup Language”) is a human readable data language most commonly used in configuration files. At its most rudimentary YAML uses easy to understand Key-Value pairs as a syntax.

In Quarto a YAML block is signified by three Dashes above and below the Code Block. In order to integrate a YAML header into your document, you need to insert the following block at the top of your document and fill the space between the dashes with relevant Key-Value pairs. Keys relevant for format and appearance will be shown in the relevant episodes!

A Key-Value pair is created by pairing a predetermined key (such as name, title, date etc.) with a corresponding value. Sub-categories are created by in indenting the line with Tab. Should these indentations not be applied correctly, certain information will not be displayed correctly or be completly hidden.

Creating a simple YAML header

Now we will try to implement some basic information into the pregenerated YAML header at the top of our document.

Discussion

Exercise

After each of the following step, try to fill out the different Key-Value pairs using your own data. Then try to render it to see the diffrence. Be careful with indentation and spaces!

First we will replace the default “Untitled” with our own title. This will replace the value of the “name” key, which was previously “Untitled”.

    ---
    title: Example The Destribution of Art in the Museum of Modern Art (MOMA)
    ---

Following this we must decide which format our final, rendereddocument should have. The two standard options are HTML or PDF. In this case we decide we want our paper to be in form of a pdf. to do this we simple add it behind the “format” key:

    ---
    title: Example The Destribution of Art in the Museum of Modern Art (MOMA)
    format: pdf
    ---

Lastly we want our document to have a simple table of contents. These tables use the Markdown headers, which were discussed in the previous lesson, to generate a table of contents for your document. In order to generate a table of contents, we use our first indented Key-Value pair. To do so we use the Tab key to indent the “toc: true” Key_Value pair. This causes it to act as an extention of the format Key-Value pair. The “true” value acts as an on/off w#switch, which activates the table of contents.

    ---
    title: Example The Destribution of Art in the Museum of Modern Art (MOMA)
    format: pdf
        toc: true
    ---
Callout

Example of a simple YAML header

    ---
    title: Example
    format: html
        toc: true
    ---
Callout

YAML Keys:

  • title: – Title of you paper/webpage/publication
  • format: – The format of your rendered document. There are a wide variety of formats to choose from. A detailed list can be found here: https://quarto.org/docs/output-formats/all-formats.html
  • toc: – Toc:true creates a simple table of contents for your website. The headings you previously created via ‘#’ are used to create and organize it.

YAML hearders for scientific publishing

There is a wide ranging assortment of YAML pairs, which are commonly used for the implementation of metadata in scientific articles. These pairs can contain a wide variety of information about the paper, its authors and its place of origin, as well as information on copyright, funding and other legal characteristics. Note that not all of the pairs are necessary, and many can be cut if they are not needed or available. Here is an overview about some commonly used Key-Value pairs:

Callout

YAML Keys

  • title: – Title of you paper/webpage/publication
  • subtitle: – Possible subtitle or clarification
  • date: – Publishing date
  • type: – Type of publication. May use EPUB Publication Types or free strings
  • author:/authors: – Names and informations on the author or authors. Can be clarified through sub categories.
  • name: – Name of an author or institution
  • id: – Identifier used to refer the author in other fields
  • orcid: – Creates a link to the author’s “Open Researcher and Contributor ID” (ORCID).
  • email: – Email adress of person or institution.
  • url – Associated website of person or institution
  • degree:/degrees: – Authors dregrees
  • affiliation – Affiliatiated institution. Can be clarified through sub categories
  • city/region/country: – Name of corresponding geographic entity
  • abstract – Abstract of the publication
  • keywords – Keywords of the publication, can be more or less detailled
  • license – A license can be either specified through a string or by inserting a Creative Commons abbrevation
  • copyright – Copyright holder. Can be clarified through sub categories
  • holder – Name of the copyright holder
  • year – Year of the copyright
  • funding – If the publication received funding it can be mentioned here

Creating a YAML hearder for a scientific document

Now that we have a wide array of possible Key-Value pairs, we can use these different options to create a detailled YAML header for our paper on the MOMA and its artworks:

Basic information

In the first part of our YAML header, we will add some basic information about our paper, building on the basics we already learned. The new Informations will be: subtitle, date of publication and type of document.

    ---
    title: The Destribution of Art in the Museum of Modern Art (MOMA)
    format: pdf
      toc: true
    subtitle: An analysis using a premade Dataset
    date: 2025-08-01
    type: education
    ---

Information about the author(s)

In the next section ofthe YAML header, more information on the authors of our paper will be added. This part is heavily reliant og the correct indentation of Key-Value pair. It helps to imagine the different amoutns of indentation as different levels of information. In this case higher tiers will contain clarifications and specification of an overarching Key-value pair. Up until now we worked in Level 1, the base level of the YAML header. To begin we will first create the “authors” key in this Level 1.

    ---
    authors:
    ---

Now we will not add a value to this key. Instead we will create several new Key-Value pairs, which will contain informations on name, IDs, email, website, degree and role. These pairs will be added under the previously created “authors” key, and will be indented. This will create a second Level in our YAML header, Level 2. This indentation will make the new pairs in Level 2 act as specifications of the “author” key. As we are planning to add multiple authors, we will add a “-” in front of the first indented Key-Value pair. Doing this will cause all following pairs on the same indentation level and without a “-”, to be countend as part of the same set of pairs.

    ---
    authors:
        - name: John Doe
          id: jd
          orcid: 0000 0000 0000 0000
          email: john.doe@example.com
          url: author-website.com
          degrees: Bachelor of Arts
          role: concept
    ---

We now also want do gove our first author an affiliation with a university. This can be done with another set of indented Key-Value pairs. To begin we add the “affiliation” key to our set of indented pairs on Level 2:

    ---
    authors:
        - name: John Doe
          id: jd
          orcid: 0000 0000 0000 0000
          email: john.doe@example.com
          url: author-website.com
          degrees: Bachelor of Arts
          role: concept
          affiliation:
    ---

Now we repeat the same process as before. We create a new set of Key-Value pairs, this time undented further than the previous ones, creating Level 3. In Level 3, we add the information on the institution that the author is empliyed by. Here we will use the keys for name, city, region, country and website.

    ---
    title: The Destribution of Art in the Museum of Modern Art (MOMA)
    format: pdf
      toc: true
    subtitle: An analysis using a premade Dataset
    date: 2025-08-01
    type: education
    authors:
        - name: John Doe
          id: jd
          orcid: 0000 0000 0000 0000
          email: john.doe@example.com
          url: author-website.com
          degrees: Bachelor of Arts
          role: concept
          affiliation:
              - name: Example University
                city: Towncity
                region: Arearegion
                Country: Countryland
                url: univerity-website.com
    ---

After we added our first author, we need to add our co-author. For this we switch back to Level 2 where we will add another set of the previously used pairs (name, IDs etc.). The first one will again have a “-”, in order to mark this as a new set of information. we will also add another Level 3 set for author twos affiliations.

    ---
    title: The Destribution of Art in the Museum of Modern Art (MOMA)
    format: pdf
      toc: true
    subtitle: An analysis using a premade Dataset
    date: 2025-08-01
    type: education
    authors:
        - name: John Doe
          id: jd
          orcid: 0000 0000 0000 0000
          email: john.doe@example.com
          url: author-website.com
          degrees: Bachelor of Arts
          role: concept
          affiliation:
              - name: Example University
                city: Towncity
                region: Arearegion
                Country: Countryland
                url: univerity-website.com
        - name: Jane Public
          id: jp
          orcid: 1111 2222 3333 4444
          email: jane.p@example.com
          url: janesawesomewebsite.net
          degrees: M.o.S.
          role: visuals
          affiliation:
              - name: XYZ Collage
                city: Villageville
                region: Random County
                Country: Republic of Example
                url: collage-page.com
    ---

Abstract and Keywords

In the following part we will switch back to Level 1, where we add two more Key-Value pairs. These will contain the papers abstract and the useful keywords. For our abtract we will add the “abstract” key, followed by a “|”. this will inform Quarto that the relevant information for the value will be addedin the next line. In the following line, we then simply add our text. As for the keywords, we use the “keywords” key. here we can add the relevant keywords as a list in the following lines. Each item on the list will be denoted with a “-”, like we did it for the different authors prviously.

    ---
    abstract: |
        This paper examines the Museum of Modern Art (MoMA) through its collection and dataset analysis. It explores the museum’s history, organizational structure, and the distribution of artworks by material, origin, and subsection. Using data visualizations, trends in acquisition, stylistic diversity, and global representation are highlighted. The study demonstrates how MoMA reflects the evolution of modern art and provides insight into curatorial practices and the broader cultural landscape.
    keywords:
    - Art History
    - Museum
    - Distibution of Material
    - Colonial studies

    ---

Continuing in Level 1 we add information on the license of our paper. Any form of license can be used as a value in this case. As we want to give to some more information on the copyright, we create a “copyright” key in Level one, before switching to Level 2 to add information on holder and year. Lastly we go back to Level one to add some information on our projects funding.

    ---
    license: "CC BY ND"
    copyright:
      holder: John Doe
      year: 2025
    funding: If your research was funded it can be written here.
    ---

The final look

After we added everything to our YAML header, it should look something like this:

    ---
    title: The Destribution of Art in the Museum of Modern Art (MOMA)
    format: pdf
      toc: true
    subtitle: An analysis using a premade Dataset
    date: 2025-08-01
    type: education
    authors:
        - name: John Doe
          id: jd
          orcid: 0000 0000 0000 0000
          email: john.doe@example.com
          url: author-website.com
          degrees: Bachelor of Arts
          role: concept
          affiliation:
              - name: Example University
                city: Towncity
                region: Arearegion
                Country: Countryland
                url: univerity-website.com
        - name: Jane Public
          id: jp
          orcid: 1111 2222 3333 4444
          email: jane.p@example.com
          url: janesawesomewebsite.net
          degrees: M.o.S.
          role: visuals
          affiliation:
              - name: XYZ Collage
                city: Villageville
                region: Random County
                Country: Republic of Example
                url: collage-page.com
    abstract: |
        This paper examines the Museum of Modern Art (MoMA) through its collection and dataset analysis. It explores the museum’s history, organizational structure, and the distribution of artworks by material, origin, and subsection. Using data visualizations, trends in acquisition, stylistic diversity, and global representation are highlighted. The study demonstrates how MoMA reflects the evolution of modern art and provides insight into curatorial practices and the broader cultural landscape.
    keywords:
    - Art History
    - Museum
    - Distibution of Material
    - Colonial studies

    license: "CC BY ND"
    copyright:
      holder: John Doe
      year: 2025
    funding: If your research was funded it can be written here.
    ---

After this we have added all of our metadata as Key-Value pairs, lets see how the renderes HRML version is in Quarto:

Discussion

Exercise

Now we will try to create a detailed YAML header for your own document. Your header should contain informations on: Author (name, email, degree, role, affiliation), title and subtitle, date, keywords, copyright and funding.

Key Points
  • YAMl headers dictate the metadata and appearence of your document.
  • YAML headers are made out of Key-Value pairs.
  • Key-Value pairs consist ofa predetermined key and a corresponding value
  • All Quarto documents contain simple YAML headers
  • Scientific papers utilize a wide variety of Key-value pairs to implement metadata

Content from Creating and implementing code for visualisations

Last updated on 2026-01-05 | Edit this page

Overview

Questions

  • How do you implement code in Quarto?
  • How to use code to create visualisations and graphs?
  • How do you annotate visualisations?

Objectives

  • Implement Python, Mermaid and Graphviz code in your Quarto document.
  • Create Visualisations of Python code using plotly.
  • Create a barchart in Quarto using Mermaid.
  • Create a flowchart in Quarto using Graphviz.
  • Enrich your generated Visualisations by adding format and information in comments.

Quarto can be used to both show and render code in a newly created document. One can basically program directly in quarto, using ones preferred coding language, and have the data rendered directly in the pdf or html document. In order to do so you need to simply insert your code into the document. In this lesson we will mostly implement python code, as well as several integrated coding languages.

Callout

Note:

By default, code inserted via Markdown will be shown as code blocks in the rendered document. If you want to use collapsable or hidden code blocks in your renders, simply add ‘code-fold: true’ to your YAML section.

One can not only insert code into one’s documents, but also directly visualize it in order to create illustrations based on the inserted code. This can be done in a variety of ways, such as using already integrated programming languages like mermaid, or by importing and using extensions like plotly in Python code cells.

Using Python:

Various python extensions can be used to plot and illustrate data in Quarto. Doing so will poste no difference to doing this in a pure Python environment. The steps needed to be performed to create and implement a wide variety of illustrations and graphs in Python are explained in the Carpenty Lesson Python101. Step 4 of the episode “Analyzing Tabular Data” concerns itself with the visualisation of tabular data.

Caution

The intricacies of creating useful charts and visualisations using various Python libraries would be too much to discuss in this lesson. We would encourage you to visit our lesson Python101 in order to learn more about this.

You simply need to insert the following part into your Quarto document in order to insert your code:

SH 

```{python}

```

If we want to insert a Python based carchart into our paper we can actually use some of the code used in the Python101 course for our paper. In the couse, a comprehensive database of artworks exibited in the MOMA is used and visualised in various form. We can use one of the code chunks used, and modify it for our puposes. As Quarto is able to read, render and calculate Python code, you can be creative and use all forms of coding used when writing Python code as a stand alone program. The result could look something like this:

SH 

```{Python}
import plotly.express as px
import pandas as pd

data_path= 'https://raw.githubusercontent.com/HERMES-DKZ/Python_101_humanities/main/episodes/data/moma_artworks.csv'
moma_df= pd.read_csv(data_path)

df = moma_df.copy()
df['Date'] = pd.to_numeric(df['Date'], errors='coerce')

top_media = df['Medium'].value_counts().nlargest(8).index
medium_df = df[df['Medium'].isin(top_media)]

fig = px.histogram(medium_df, x='Date', color='Medium',
                   nbins=50,
                   title='Trends in Medium Usage Over Time: the Top 8 Media')

fig.update_xaxes(title_text='Year')
fig.update_yaxes(title_text='Number of Artworks')

fig.show()
```

Using the Plotly library, the python code is now loaded into our quarto document and will be shown in our rendred document as a barchart.

Using this Code chuck in VSCode could look like the following example:

Caution

Caution!

Not all forms of visualisation work in every format. In this example Plotly only works in html formats, not in pdf or similar formats.

Using Mermaid:

One of the coding languages already integrated in Quarto is Mermaid. Mermaid is a simple, text-based diagramming and visualization language that lets you create flowcharts, sequence diagrams, Gantt charts, class diagrams, and more using plain text. It uses a very simple text-based programming language. To make the work with Mermaid easy, you can use one of several web-based Mermaid editors. These allow you to create your graphs visually and copy the underlying code. You can then paste this code into your Quarto document. One of these Website is Mermaid.live.

In order to use Mermaid, simply put your mermaid text into the following part:

SH 

```{mermaid}

```

Using Mermaid to create a piechart :

A commonly used graph, which can be used and implemented to visualize a wide variety of data, is the piechart. It offers an easy and comprehensive form of displaying percentages and relative strength of different aspects of data. A bar chart can be easyly implemented into a Quarto document using the implemented Mermaid language. For our scientific paper, we can create a pie chart, showing the relative distribution of the eight most used Media in the MOMA, that were created between 1930 and 1934. It is split into eight categories, representing each medium . Each categorie is represented by an indented Key-Value pair, with the titles of each categorie funntioning as the key. The value of each key contains the total number of the relevant media added. When rendered the pie chart will not show the numbers used in the code. Instead it will show the percentage of the categorie relevant to the total amount of media, made up pf all eight categories combined.

SH 

```{mermaid}
pie title Medium Distribution, Top 8 1930-34
    "Lithigraphy" : 320
    "Etching" : 49
    "Pencil on tracing paper" : 589
    "Letterpress" : 225
    "Pencil on paper" : 97
    "Gelatin silver print" : 777
    "Alburnen silver print" : 0
    "Chromogenic print" : 0
```

The resulting pie chart would look like this in your rendered paper:

Discussion

Exercise 1: Mermaid

Try to create your own pie chart. Try out different numbers of categories and change the associated values to experiment on how the resulting graph will change.

Using Graphviz

Similar to Mermaid, Graphviz is an integrated coding language, which uses simple text-based descriptions of charts in order to create visualisations. Where Mermaid is mostly used for common or simple charts and graphs, Graphviz can be used to create more complex forms of visualisations and workflows. Like with Mermaid, the simplest way to use Graphviz with Quarto is to use a web based Graphwiz editor and copy the resulting code into your Quarto document, this time using:

SH 

```{dot}

```
Callout

Creating a flow chart in Graphviz:

One of the possibilities Graphviz offers is the abilities to quickly create flow charts in your Quarto document. As an example we will create a simple and small flow chart showing the process of coding in Quarto: The code is split into 4 sections: The first section is made out of the name of the graph. It creates the “borders” of the remaining code, which is later placed inside the {} brackets. The second section established the different categories and steps in the flowchart. In our example each of these are made out of an internal name (here for example “code”, “works”, “try” and “retry”), a label, which establishes what will be written inside the shape, and the form of the shape itself (rectangle, oval, diamond etc.) The third step establishes the connections between the shapes created in step 2. Here Graphviz uses an easy to understand concept: Connections between different shapes/categories are depicted in the code as arrows. The arrow can be labled with text or flipped by adding the relevant code ( “label =” for text, “dir=back” for a flipped arrow) behind the newly created directional pair. The forth step {rank = same} is optional and dictates that the three categories “try”, “works” and “retry” will be displayed next to each other as they are now on the same rank.

SH 

```{dot}
digraph G {

  code [
    label = "Try to code in Quarto";
    shape = rect;
  ];
  works [
    label = "You win!";
    shape = oval;
  ];
  try [
    label = "Did the code work?";
    shape = diamond;
  ];
  retry [
    label = "Change things\nuntil it works.";
    shape = rect;
  ];

  code -> try;
  works -> try [ label = "Yes"; dir=back ];
  retry:s -> try:s;
  try -> retry [ label = "No" ];
  {
    rank=same;
    try; works; retry; 
  }
}
```
Discussion

Exercise 2: Graphviz

Try to create your own flow chart. Try out different numbers of categories and change the connections and directions to experiment on how the resulting flow chart will change.

Adding information

When implementing visualisations, it is always important to add relevant information in form of titles, descriptions etc to the chart. This can be done by inserting the relevant information into the relevant code chunk in form of comments.

Callout

Here one can use the same commands that are also used for the sizing and descriptions of pictures and illustrations. An overview of the possibilities can be found here

For our Example we, will now try to add some additional informations to our Mermaid pie chart: First we will give it an actual internal name. This can be done by adding the Key-Value pair “label: ‘selected name’” as a comment to your code. In order to keep it simple we just choose “Illustration 1” Then we add a caption for our illustration. Here we also use a Key-Value pair, this time with the Key “fig-cap”. This will create a caption for our illiustration. lastly we want to limit how wide our newly created graph will be when displayed. This can be done by adding a third Key-Value pair, this time with the “fig-width” key.

SH 

```{mermaid}

pie title Medium Distribution, Top 8 1930-34
    "Lithigraphy" : 320
    "Etching" : 49
    "Pencil on tracing paper" : 589
    "Letterpress" : 225
    "Pencil on paper" : 97
    "Gelatin silver print" : 777
    "Alburnen silver print" : 0
    "Chromogenic print" : 0
%%| label: Illustration 1
%%| fig-cap: "Medium Distribution, Top 8 1930-34"
%%| fig-width: 6.5
```
Caution

Caution:

Every Coding language has a different way of creating comments. The ones used in this Lesson are the following:

Python: ##| Mermaid: %%| Graphviz: //|

Content from Quarto for PDF and HTML

Last updated on 2026-01-05 | Edit this page

Overview

Questions

  • What unique options exists for PDFs in Quarto?
  • What unique iptions exists for HTML in Quarto?

Objectives

  • Implement format, font and documentclass characteristics in a PDF Quarto document.
  • Implement themes in a HTML Quarto document.

Every different Format of Quarto has its own unique commands and output specific code. These are most often part of the YAML header. As there is a large array of possible Ley-Values, makng it possible to customize many different and minute aspects of Quarto, we will only show you some of the more simple and easy to understand Key-value pairs. But as the theory behind all YAML pairs and their resulting changes and modifications are the same, you can freely experiment with all offered possibilities to find the options that fit your preferred visual and editorial srtyle.

PDF

In the case of a PDF, these mainly dictate things such as the font used, the dimensions of the PDF and the class of PDF used.

A comprehensive overview over all possible YAML commands can be found here

Documentclass

The documentclass given in YAML functions as a shorthand used to immediately change a variety of characteristics. The main documentclasses used in Quarto PDFs are: article, book and report.

These classes offer the following benefits:

Article: - used mainly for short texts, not divided into chapters - formatted in single column texts with author and title of the article at the top

Report: - used mainly for longer texts, which are divided into different chapters - automatically generates a frontpage with author and title

Book: - used for publishing and complete books - supports division into frontmatter, main matter and back matter - integrates publishing and print friendly dimensions

Fonts and colours

Quarto allows you to edit every font used by different syntaxes in its YAML header. To do so you can add the relevant font type followed by a typeset into the header.

For example:

YAML 

mainfont:  "Times New Roman"  Sets Times New Roman as font for the main text
sansfont: "Open Sans"         Sets Open Sans as a font for headings
    - Color=39729E            Sets the Color of headings using a HexCode

The color of different parts of the PDF can be changes using a similar code.

for example:

YAML 

linkcolor:    Sets the color for links
toccolor:     Sets the color for the Table of Contents

Layout

Lastly one can use a variety of command in order to change the general layout of the document, such as margins, paper size and geometry.

YAML 

title: "My Document"
format: 
  pdf: 
    documentclass: article
    geometry:
      - top=30mm
      - left=20mm
      - heightrounded

HTML

Many of the options available for PDFS are also or similarly available for HTML based Quarto documents. They allow you to customise familiar options such as the Table of Contents, fonts or visibility of links. A comprehensive overview over all available options can be found here

A more unique possibility for HTML formats is the so called themes, which allow you to give your website a more concise and complete visual overhaul. They change a variety of aesthetic characteristics such as highlight colours, fonts and layout. Quarto uses a 25 themes from the Bootswitch project. A full overview can be found here Multiple themes can be used in order to for example implement a Dark and Light mode to your website. To implement such a theme you simply need to add it to your YAML header like this:

YAML 

  html: 
    theme:
      light: united
      dark: darkly

The following example uses the two styles shown above:

Discussion

Exercise:

Decide if you would like to continue with a PDF or HTML. Then try out the new YAML headers and options in your document. Be creative!

Content from Using the Bibliography

Last updated on 2026-01-05 | Edit this page

Overview

Questions

  • What is the bibliography feature in Quarto?
  • How do you use and expand the bibliography and citations?
  • How do you implement footnotes?

Objectives

  • Learn the basics of citations and footnotes in Quarto.
  • Learn to insert footnotes.
  • Learn to create citations in a document.
  • Learn to find publications in the integrated databases and insert them manually into your references file
  • Learn how to expand your bibliography.

One of the most important aspects of scientific publishing is the inclusion and organisation of sources,. citations and footnotes. These are all included in Quarto, which offers an integrated menu to organize and implement Citation from a variety of different sources.

Callout

For this part of the lesson, we will switch from Source Mode to Visual Mode, in order to offer you an easier to understand guide on how to use these.

Footnotes:

Footnotes offer an easy way to add useful information or literature to your text. They can be implemented into your Quarto document by using the Insert -> Footnotes option in the Visual Mode of Quarto.

Let us now add a quick footnote to our paper on the MoMA. In order to do so we just have to add the text for our footnote into the new textbox on tghe lower part of the VSCode window:

Citations

In a similar vein to footnotes, you can also directly add citations to your document. This can be done through the Insert window of the Visual Mode:

Doing so will accomplish two things: It will open a new window called “Insert citation”, and it will create a new file called “references.bib” in your working folder.

This new file will contain your newly created bibliography, which can now be filled in a variety of ways. The easiest to do are the four already integrated options of either searching for a publication through their DOI (a unique number given to all published articles and books) or by searching through the databases of Crossref, Datacite or Pubmed. Simply add relevant information such as the DOI, Title or name of the author into the search bar and see what you can find there. In the best case your needed citation is already part of one of these databases.

In our paper we want to reference Alan Wallachs scentific reviiew of the book “Museums and American Intellectual Life, 1876–1926” by Steven Conn. In order to do so we can simply search for Alan Wallachs name using the Crossref database.

By pressing the + button on the right, we can quickly add it to our bibliography.

We also want to add a refernce to the the article “Selling the American Dream: MoMA, Industrial Design and Post-War France” by Gay McDonald. As we are not able to find the article using the integrated databanks, we have to add it manually. In order to do this, you need to open your newly created references.bib file with a text editor of your choice. This can also be done in Visual studio code.

In this file you will find all your already added references in form of code chunks. The citation function uses a format called Bibtex, which is used by a variety of databases. It is in part made up of a reference name, signified by a @, which is used internally as a unique signifier of this specific reference. Following this are the reference name, which will be shown in your Quarto document when using the citation function, and a variety of information inside {} brackets. These contain the relevant metadata of the publication.

You can now simply add further objects to your list of references by either manually typing in additional sources, or by copy and pasting the relevant BibTex chunks from other websites. Many Websites used to publish academic texts, such as Jstor, or libraries offer the download oft txt files containing the relevant BibTex Chunks as part of their own citation functions. Here is an example using Jstor:

And here is how it looks when added to your reference.bib file:

Once you have added the new code chunk to you refernces.bb file, you can save (Ctrl+S) and return to your “Insert Citation” window. Here you will now find your newly added reference as part of you bibliography:

Now you can simply click on the different references in order to insert them into your work. In our case we want to add McDonalds article as areference into our text. This will create a reference in the following format: [[@63aecae8-5ed6-394e-883b-12026c168381]] in source mode. The rendered Document will have the Authors name and the publication date in brackets in its place. Using the reference feature will also create a reference index at the bottom of your rendered document. This index will contain a full bibliographical list of all used refences, using the information contained in the reference.bib file. The result could look something like this:

Discussion

Exercise

Use the References and Footnote features to enrich your document with citations.
Create and fill out a bibliography, then render your document one last time.

Content from Creating a simple website with Quarto

Last updated on 2026-01-05 | Edit this page

Overview

Questions

  • How to create a website using Quarto?
  • What seps and components are necessary to create a website with Quarto?

Objectives

  • Learn how to create a .yml file to connect your Quarto documents.
  • Learn the contents of a .yml file.

A more advanced function of Quarto is, that users can not only create simple and standalone html pages and documets, but can also create more complex and connected webpages. These webpages need a more complex structure of pages and files.

Creating the necessary files

In order to create our website, we first need to plan how we want our website to be structured. All files and must be situated in the same folder in order for our website to function! In this case we want to have three main pages: A homepage, as well as two further sections about the history and the collections. The history section should have to subpages for the founding and the current history.

Creating a new folder

Let us start with the most basic step: the creation of a new working folder. Like in the previous lesson we first create a new folder called “moma_website” on our computer. Then we open this folder in VSCode using the navigation bar on the left side. This dolder will now contain all pages, images and ressources needed to create our website. We will slowly add more and more documents as our website grows.

Creating our pages

Creating the mainpage

First we will create our mainpage, which will serve as our starting point and the first page a viewer of our website will most likely see. in order to do so we create a new document in our folder by navigating to the left side of the VSCode window and selecting “New File” option under “File”. We then choose to create a Quarto document. By saving it (Ctrl+S), we can name it.

Caution

Important!

Where we previously had comple freedom when it came to naming our document, this one need to have the name “index.qmd” in order to function as our mainpage!

Once we named our webpage, we an start filling it.

We start with a very simple YAML header. In contrast to our previous headers, this one only need to Key-Value pairs: the title and the format. While the format needs to be set as html, when deciding on the title you again have complete freedom.

Always try to choose speaking and easy to understand titles and filenames, in order to avoid confusion or mishaps!

In our case we will give this page the title “mainpage” and start to fill it with text and other media. The filling of our document follows the same rules and steps that you have learned previously. You can simply add a header by using # and hen add some text. When we do this with our main page it could look like this:

Adding pictures

We now want to add a picture of the MoMA to our main page. In order to do so we can use the same syntax we used to add pictures to our previous documents. To make sure our pictures can always be accessed we will add them to our folder as a ressource. This can be simple done by copying the chosen file into our folder. But while this is the easiest solution, it also can get disorganized and chaotic fast, if you choose to add a lot of different images to your website. Because we want to try to keep our folder structure neat and easy to navigate we will put our images into a new folder calles “images” which we will put into our “moma_website” fodler. Now we add our picture into this newly created folder:

When we now want to insert this image into our main page we simple have to enter the following code into our Quarto document:

![](images/moma_image.png)

As you can see we have inserted the relevant folder, in this case “images”, and the name of the chosen picture, in this case “moma_image.png”, into the brackets.

Creating the other pages

Now we can save our mainpage and continue creating our three remaining pages. These follow the same steps as creating our main page, with one exception: We are again free to choose the name of our files. We now create three more pages: One page for the museums collections, and two pages for its history. We again create a file for each page, fill a simple YAML header with title and html format, and then fill our page with headers, text and images. When done we have thre more pages with the filenames collections.qmd, founding.qmd and modernhistory.qmd.

The YAML File

Creating the .yml file

Up until now he have just created a couple of Quarto files in the html format. These will not interact with each other or act as anything other than singular documents. We have also used just the barest minimum of YAML headers in these files. In order to connect our different document and give our files the needed formatting and metadata we will now have to create the heart of a Quarto website: The YAML-File!

To create this file we again navigate down the “File” -> “New File” path, as we did with our other documents. But instead of choosing to create a Quarto document, we will now enter something different into our text window.

Caution

Important!

Like with our mainpage, this file also needs a very specific name: “_quarto.yml.” You see the file ending is now .yml insted of .qmd.

It will look like this in VSCode:

Filling the .yml file

Now that we created our YAML file, we need to fill it with the specific Key-Value pairs needed to create a website.

In order to do so the file needs three sections: The “project” section, the “website” section and the “format” section.

The project section

The project section is located at the beginning of the document and consists of the following elements:

type:        This sets the type of structure and entities this YAML file will create. In our case this will be set to "website"
output-dir:  This will dictate where the rendered html files for our webpage will be stored. it will also create a folder with the name put as a value. In our case this will be "public/"
ressources:  This will dictate which folders will contai ressources used for this website. You can create and enter multiple ressource folders for images, videos, audiofildes etc. in our cas e will will enter our previously created "images/" folder.

When we have entered everything our project section ourld look like this: {YAML} project: type: website output-dir: "public/" resources: - "images/"

The website section

The “website” section of the YAML file will contain the most information and create the connections between our different Quarto documents. It contains the following elements:

title:   The name of our Website
image:   Here you can put an image file that will act as a logo for the website. it will be the picture displayes next to the title and in the tab of the browser
navbar:  this will create the navigation bar at the top of the website. This will be used to connect our different Quarto html pages. The navbar consists out of multiple Key-             Value pairs that are indented:
    left/right/center:  The different areas of the navigation bar can be filled up seperatly with different elements. To do so simple add the corresponding positiona and add the                         relevant elements indented after it.
    href + text:        "href" contains the file names of your Quarto documents, while "text" contains the official names of these pages, which will be shown in the navigation                           bar. They are added below each other, with only href having a "-" in front of it
    text + menu:        If you want to have one navigation bar item to consists of multiple subpages, you can add them using these Key-Value pairs. "Text" will determine the                             name of the overarching navigation bar item. The different subpages can then be added by inserting the filenames of the relevant Quarto files as part of                          the "menu" element. The names shown for these subpages in the navigation bar will be determined by the title given in the YAML header of the document.
    icon + href:        This combination of Key-Value Pairs can be used to create clickable icons that will act as links to erelevant websites such as gitlab, github or                                  different social media sites. "Icon" will determine the oüptical aspect and can be filled with any image file. Quarto also has already a large variety of                         integrated icons for most social media platforms and datashating websites (such as github, etc.), they can be used by simply writing the name of the                              platform as the value. "href" will contain the relevant webadress for the link.
page-footer:  This elemet is used to create a footer for your website. Like the navigation bar, it can also be divided into left, right and center. It can also contain a variety               of icons, text or images. Icon can be added by using the previously mentioned "icon + href" element, while text can be added via the "text" element.

We now want to create the 2website section of our MoMA website. As the title of the website we choose “A Short Guide to the MoMA” For our image we found a good looking logo of the museum. We put the logo under the name “moma_icon.png” inro our previously created “images” folder. We want the navigation bar to be sepetarted into two sections. On the left we want to have our different pages. Our starting page will be calles “Home” in the navigation bar. Our page about the Collections can be found under “Collections”. And our two subpages about the Founding and the modern history of the MoMA will be found under the name “History of the MoMA”. On the right side we want to add an icon that leed to the GitHub page of the project. As a footer we simply add a textblock in the center. It will contain the names of our authors as well as their universities.

When we add all this information into our YAML file, it could look somewhat like this:

``` {YAML} website: title: “A Short Guide to the MoMA” image: “images/moma_icon.png” navbar: left: - href: index.qmd text: Home - href: collections.qmd text: Collections - text: History of the MoMA menu: - founding.qmd - modernhistory.qmd right: - icon: github href: https://github.com/ExampleUser/MoMA_website/main

page-footer: center: “© John Doe, Jane Public
Example University / XYZ Collage”


##### The format section

lastly we need to add the Key-value pairs that determine the appearence of our website. In this section we can use the same commands and Key-Value pairs previously discussed in Section 6 of the course.
We choose to use twi themes in order to create the option for a light and dark mode. For the light theme we choose the theme "united", while for the dark theme we choose "darkly".
We also want our website to contain tables of content in the different pages.

Wenn added to the YAMl file our "format" section looks like this:

``` {YAML}
format:
  html:
    theme:
      light: united
      dark: darkly
    toc: true

When all of these elements are added, we can save our .yml file and render our finished website.

The finished website:

Now that we have added everything our “moma_website” o#folder should look something like this:

And our rendered result like this: