QUARTO: INTRO TO A NEW PUBLISHING SYSTEM

Harrie Jonkman

NSC-R workshop 11-4-23

Hi everybody! Thank you so much for joining today’s session. I am so excited to introduce Quarto and many thanks to the NSC-R-team for having me today.

Introduction

Agenda

1. Introduction

2. About Quarto

3. How Quarto works

4. Blog as an example

5. Conclusion

Hello!

My name is Harrie Jonkman.

Here you find some information about myself. Here also

I have a science data blog Harrie’s Hoekje here,

I worked recently on a book together with David Farrington (UK) and Frederick Groeger-Roth (Germany) here.

I review books on democracy and education, recently for example I started here

And on this moment I finish my book on poetry of Billy Collins here

My name is Harrie Jonkman. I worked in the field of education and prevention, youth development and research. The last 15 years I worked at the Verwey-Jonker institute and since a few months I’m retired. I still work on research projects and have my own datascience blog, but do also other things

About Quarto

Agenda

1. Introduction

2. About Quarto

3. How Quarto works

4. Blog as an example

5. Conclusion

What is Quarto®?

Quarto® is an

open-source

scientific and technical

publishing system

built on Pandoc

Quarto is an open-source scientific and technical publishing system built on Pandoc. Let’s break this down: Open-source. Free software means more reproducibility, widespread sharing of knowledge and techniques, and elimination of cost barriers. You can also see the source code and contribute, too. Scientific and technical: Scientific and technical means that Quarto has specific things for journal articles or scientific papers, like support for code execution, citations, footnotes, scientific markdown, equations, citations, crossrefs, so many things. We’ll be showing some of these later on, but Quarto definitely has the scientific publishing audience in mind. Publishing system: Quarto is a tool for writing dynamic documents that combine code, output, and text. It can embed output from Python, R, Julia, and Observable. Quarto can be rendered to create high-quality articles, reports, presentations, websites, blogs, and books in HTML, PDF, MS Word, ePub, and more formats. Pandoc is the tool working behind the scenes to change Quarto documents to their finalized format.Quarto documents are authored with markdown, which is a plain text format. But Pandoc markdown is very rich and lets you control your document in very specific ways while being easy to read and write. We’ll cover this as well.

Quarto Advantages

Quarto®

incorporates different packages in one system

at its core, Quarto is multilingual and independent of computational systems

expands upon R Markdown to add new languages and can add more in the future

has lot of new features

It is not necessary to open specific packages every time (blogdown for blogs, bookdown for books etc). Quarto has everything inside. It works on different systems, not only with R but also with Python, Julia and Observable. It builds on R Markdown with new features.

Quarto Goals

These are

create computational documents that hold source code for automation and reproducibility

reduce how difficult it is to make a scientific document

enable “single-source publishing” — create Word, PDFs, HTML, etc. from one source

So the goals are to create these dynamic documents that can be reproducible and automated. For single-source publishing, you often need to create all sorts of output, like things that are printed, on the web, on the mobile. The idea is to being able to make publications from one source.

How Quarto works

Agenda

1. Introduction

2. About Quarto

3. How Quarto works

4. Blog as an example

5. Conclusion

Working in RStudio

Rendering

Use the Render button () in the RStudio IDE to render the file and preview the output with a single click or keyboard shortcut (⇧⌘K).

Automatically render on save by checking the Render on Save option:

In RStudio, you can use the Render button to render the file, or take it through that process of convering to markdown, pandoc processing, etc. and preview the output with a single click. If you’re familiar with R Markdown, it is where the knit button would show for those document. If you prefer to automatically render whenever you save, you can check the Render on Save option on the editor toolbar. The preview will update whenever you re-render the document. Side-by-side preview works for both HTML and PDF outputs.

YAML Intelligence

YAML code completion is available for project files, YAML front matter, and executable cell options:

If you have incorrect YAML it will also be highlighted when documents are saved:

Quarto has YAML intelligence in RStudio and VS code. YAML intelligence means completion and diagnostics for errors, and its’ available for project files, YAML front matter, and executable cell options. This makes it easy to write YAML and see what has gone wrong rather than getting error messages that are really hard to decipher.

Working with the RStudio Visual Editor

RStudio has two options for editing documents: visual (on the left) and source (on the right). RStudio’s visual editor offers an WYSIWYM authoring experience for markdown. So formatting (e.g. bolding text) you can use the toolbar, a keyboard shortcut (⌘B), or the markdown construct (bold). The plain text source code underlying the document is written for you and you can view/edit it at any point by switching to source mode for editing. You can toggle back and forth these two modes by clicking on Source and Visual in the editor toolbar (or using the keyboard shortcut ⌘⇧ F4).

Contents of a Quarto Document

A Quarto document contains three types of content: a YAML header, code chunks, and markdown text.

Code Chunks

• Code chunks begin and end with three backticks (usually)
• Code chunks are identified with a programming language in between {}
• Can include optional chunk options, in YAML style, identified by #| at the beginning of the line

Code chunks are identified with three backticks, the language in curly brackets, and can have optional chunk options identified by the hashpipe at the beginning of the line within the chunk.

Code Chunks

```{r, label="plot-penguins", warning=FALSE, echo=FALSE}
ggplot(penguins, 
       aes(x = flipper_length_mm, y = bill_length_mm)) +
  geom_point(aes(color = species, shape = species)) +
  scale_color_manual(values = c("darkorange","purple","cyan4")) +
  labs(
    title = "Flipper and bill length",
    subtitle = "Dimensions for penguins at Palmer Station LTER",
    x = "Flipper length (mm)", y = "Bill length (mm)",
    color = "Penguin species", shape = "Penguin species"
  ) +
  theme_minimal()

## Code Chunks {.small auto-animate="true"}

``` markdown
```{r}
#| label: plot-penguins
#| warning: false
#| echo: false

ggplot(penguins, 
       aes(x = flipper_length_mm, y = bill_length_mm)) +
  geom_point(aes(color = species, shape = species)) +
  scale_color_manual(values = c("darkorange","purple","cyan4")) +
  labs(
    title = "Flipper and bill length",
    subtitle = "Dimensions for penguins at Palmer Station LTER",
    x = "Flipper length (mm)", y = "Bill length (mm)",
    color = "Penguin species", shape = "Penguin species"
  ) +
  theme_minimal()

## Code Chunks {.small auto-animate="true"}

``` markdown
```{r}
#| label: plot-penguins
#| warning: false
#| echo: false
#| fig.alt: "Scatterplot with flipper length in millimeters on
#|  the x-axis, bill length in millimeters on the y-axis, colored
#|  by species, showing a slightly positive relationship with
#|  Chinstrap penguins having higher bill length but lower body
#|  mass, Adelie with low bill length and low body mass, and
#|  Gentoo with high body mass and high bill length."

ggplot(penguins, 
       aes(x = flipper_length_mm, y = bill_length_mm)) +
  geom_point(aes(color = species, shape = species)) +
  scale_color_manual(values = c("darkorange","purple","cyan4")) +
  labs(
    title = "Flipper and bill length",
    subtitle = "Dimensions for penguins at Palmer Station LTER",
    x = "Flipper length (mm)", y = "Bill length (mm)",
    color = "Penguin species", shape = "Penguin species"
  ) +
  theme_minimal()

```

The new hashpipe allows for consistency across Jupyter and knitr.

Blog as an example

Agenda

1. Introduction

2. About Quarto

3. How Quarto works

4. Blog as an example

5. Conclusion

New repository on GitHub

Create a project for the blog

Project Type

## Create Quarto Blog

Structure of the blog

Send it over to repository and add blogs

Restyle the blog

Different possibilities

25 styles inbuild styles

about site and 5 possibities

with css or scss file you style it yourself

Different styles

• Cosmo
• Darkly
• Sketchy

Different about sites

• Jolla
• Trestles
• Solana
• Marquee
• Broadside

Change of css/scss file

Deploy it by Netlify

Site setting

## Change site name

Change site name2

Result

Here you see the result

Publish it

Different possibilities also

Quarto pub

Git Hub pages

rconnect or positconnect

Netlify

Your own deploy system

Conclusion

Agenda

1. Introduction

2. About Quarto

3. How Quarto works

4. Blog as an example

5. Conclusion

Conclusion

Quarto is a perfect technical and scientific system for

sharing

teaching

reimagining

collaboration

Thank you!

I hope that you enjoyed this intro to Quarto!

• Read the Quarto documentation.
• Check out Awesome Quarto.
  
• My presentation you find here. Information about article-writing here and information about the blog here
• On my HarriesHoekje-blog I wrote a blog about making and publishing a blog. You find it here

Acknowledgements

• Isabelle Velasques
• Albert Rapp
• Bea Milz
• Tom Mock
• Mine çetinkaya-rundel