Quarto: markdown-based document creation/edition

Static website generator and more

This is a Quarto website using Markdown files to write contents: webpage including a presentation and sources.

This work is licensed under a Creative Commons Attribution 4.0 International License (CC BY 4.0)

What is Quarto?

Quarto is an open-source scientific and technical publishing system built on Pandoc

Create dynamic content with Python, R, Julia, and Observable.

Author documents as plain text markdown or Jupyter notebooks.

Publish high-quality articles, reports, presentations, websites, blogs, and books in HTML, PDF, MS Word, ePub, and more.

Author with scientific markdown, including equations, citations, crossrefs, figure panels, callouts, advanced layout, and more.

Documentation

Getting started
Create websites based on (R|Q)markdown files
Detailed tutorials
Full documentation
R Interface to ‘Quarto’ Markdown Publishing System

Under the hood

pandoc: “a universal document converter”

Creating a website with quarto

Command line:

quarto create-project <my_website_name> --type website

Rstudio:

new project -> quarto website

Quarto markdown files

Use Quarto markdown (.qmd) files to write your contents, following the standard Markdown syntax with the additional features to run computations, similarly to Rmarkdown.
Also natively render Rmarkdown (.Rmd) files and Jupyter notebook (.ipynb) files.

Rendering your website from notebook sources

Command line:
- only build: quarto render <path/to/my_website_name>
- build + preview: quarto preview <path/to/my_website_name>
Rstudio: Render button to build + preview (when editing any notebook file)
- run a local server that updates the website when any notebook (.qmd, .Rmd, .ipynb) file is edited (but not any included markdown .md file)
See also quarto R package: quarto::quarto_render() and quarto::quarto_preview()

Running computations inside (Q|R)markdown sources

You can include code chunks between ```{r} and ``` markers (with the name of the language between { }), and the code as well as its output will be included, e.g. in R:

x <- seq(0, 10, 0.1)
plot(x, cos(x))

R, Python and Julia programming languages are supported.

Another example in Python:

a = []
for i in range(10):
    a.append(2*i)
print(a)

[0, 2, 4, 6, 8, 10, 12, 14, 16, 18]

Requirements for computation

Running R codes requires the knitr R package.
Running Python codes requires the reticulate R package when using Rstudio, and the jupyter Python package when using the command line interface.

Additional tips

You can include markdown (.md) files inside any (Q|R)markdown file with the following

{{< include my_file.md >}}

Configuring your quarto project

File _quarto.yml

More complicated example: quarto website config

project:
  type: website

website:
  title: "Quarto Website Template"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd
      - href: presentation/slides_presenting_quarto.qmd
        text: Presentation

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

Website and content organization

All notebooks (.qmd, .Rmd, .ipynb) in any sub-directory are rendered in the website (e.g. subdir/myfile.Rmd automatically rendered to subdir/myfile.html)
Other content are automatically included in the website file tree (e.g. included images)

Automatic gitlab pages setup

CI setup

.gitlab-ci.yml file for automatic gitlab pages generation:

pages:
  image: registry.gitlab.com/quarto-forge/docker/quarto
  script:
    - quarto render --execute --to html --output-dir public
  artifacts:
    paths:
      - public

Docker images

rocker: “Docker Containers for the R Environment”

image: rocker/rstudio

Quarto container

# Python
image: registry.gitlab.com/quarto-forge/docker/python
# R
image: registry.gitlab.com/quarto-forge/docker/rstats
# both
image: registry.gitlab.com/quarto-forge/docker/polyglot