title: "Quarto: markdown-based document creation/edition"
subtitle: "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?

Per the Quarto official website:

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

  • Quarto and Rstudio
  • Quarto and Jupyter Notebook
  • Quarto in your text editor

• Create websites based on (R|Q)markdown files

• Detailed tutorials

• Full documentation

• R Interface to 'Quarto' Markdown Publishing System

Under the hood

:::: {.columns}

::: {.column width="70%"}

pandoc: "a universal document converter"

:::

::: {.column width="30%"}

:::

::::

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)

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

:::: {.columns}

::: {.column width="40%"}

File _quarto.yml

More complicated example: quarto website config

:::

::: {.column width="60%"}

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

Other type of contents

Documents

• pdf
• html
• book
• interactivity: Observable JS, shiny app, Jupyter Widgets or htmlwidgets

Customization

• css and local styles.css file
• extensions: template for journal articles, presentations, web pages

Example: https://computo.sfds.asso.fr/published-paper-tsne/

Alternatives

R-based:

• Rmarkdown + knitr R package with LaTeX style or CSS style, but file per file rendering (requires to manually manage multiple files rendering into a website)

• pkgdown, blogdown, bookdown R packages for Rmarkdown-based document generation (with a specific aim)

Other:

• Hugo static website generator based on markdown (restricted to web content creation, multiple community templates)

• jekyll static website generator

• and more...