Comunicando seus resultados: Criando apresentações com Quarto

Beatriz Milz

Latin-R 2022 | Outubro 2022

Slides: beatrizmilz.github.io/2022-latinr-quarto-tutorial

Beatriz Milz 🇧🇷

• Contato

  • Twitter: @BeaMilz

  • Blog: beamilz.com

• Sobre mim

  • Co-organizadora: R-Ladies São Paulo / Latin-R / satRday São Paulo

  • Professora na Curso-R

  • Instrutora de Tidyverse certificada pela RStudio

Tarefas iniciais

Caso não tenha, crie uma conta nos serviços:

• RStudio Cloud: https://rstudio.cloud/

• QuartoPub: https://quartopub.com/

Dica: Você pode criar uma conta vinculada ao Gmail ou GitHub.

Objetivos de aprendizagem

Responder as seguintes perguntas….

⬜ O que é o Quarto?

⬜ Como criar um documento simples ?

⬜ Como criar uma apresentação?

⬜ Como disponibilizar a apresentação online?

⬜ Como alterar o estilo da apresentação?

Sobre esse tutorial….

Faremos muita prática!

Tem novidades surgindo com frequência!

O que é o Quarto?

Seria o Quarto…

O que é o Quarto?

• O Quarto é um sistema de escrita técnica e científica, de código aberto.

A schematic representing the multi-language input (e.g. Python, R, Observable, Julia) and multi-format output (e.g. PDF, html, Word documents, and more) versatility of Quarto

Por que o Quarto existe?

• O Quarto é a nova geração do R Markdown!

• O rmarkdown é um pacote em R. Para usá-lo, é necessário ter o R instalado (mesmo que o seu arquivo não tenha conteúdos em R).

• O R Markdown é uma ferramenta muito boa para escrita técnica e científica reprodutível, possibilitando criar vários tipos de documentos. Porém, o seu uso acaba ficando limitado às pessoas que usam R.

• O Quarto é um software novo, que não depende do R!

• Por exemplo: Você pode usar o VSCode como IDE, escrever um documento com código em Python e gerar o documento final. Tudo isso sem precisar ter o R e/ou RStudio instalados.

Quais são as similaridades?

• A estrutura do arquivo é muito similar! Para muitos arquivos, há compatibilidade (bastando alterar a extensão de .Rmd para .qmd).

• Podemos adicionar código em R, Python, Julia, etc etc.

• Podemos criar diversos tipos de arquivos, como: páginas da internet (arquivos .html), PDFs, .docx, apresentações, documentos interativos, livros, e mais está sendo produzido :)

Como começar a usar o quarto

Instalar o Quarto:

Como criar um documento simples?

Vamos usar o Quarto na RStudio Cloud!

• https://rstudio.cloud/content/4688214

• Similar ao RStudio IDE

• O quarto já vem instalado!

Engines

• Ao criar um novo arquivo com Quarto, podemos escolher entre duas engines: knitr ou jupyter.

Com knitr

Caso não tenha o pacote rmarkdown instalado, execute no console:

install.packages("rmarkdown")

Com jupyter

Caso não tenha o jupyter instalado, execute no terminal:

python3 -m pip install jupyter

Criar novo arquivo: New file

Renderizar o arquivo: Render file

Visual Editor

• As versões mais recentes do RStudio permitem usar o Visual Editor.

Leitura indicada:

• Exploring RStudio’s Visual Markdown Editor

Fonte: RStudio

Vamos praticar!

Como criar uma apresentação?

Altere o cabeçalho do arquivo

---
title: "Título"
format: html
editor: visual
---

Altere o cabeçalho do arquivo

---
title: "Título"
format: revealjs
editor: visual
---

• Os slides são separados considerando os títulos e subtítulos: # e ##.

• Use # para criar uma nova seção.

• Use ## para criar um novo slide.

Vamos praticar!

Como compartilhar a apresentação?

Algumas formas…

• GitHub Pages

• Netlify

• QuartoPub

Primeiros passos usando Quarto na linha de comando

• O Quarto é um CLI: Command Line Interface - Interface de linha de comando.

• Podemos usar o Quarto no terminal.

/cloud/project$ quarto help

  Usage:   quarto 
  Version: 1.1.251
                  

  Description:

    Quarto CLI

  Options:

    -h, --help     - Show this help.                            
    -V, --version  - Show the version number for this program.  

  Commands:

    render          [input] [args...]   - Render input file(s) to various document types.            
    preview         [file] [args...]    - Render and preview a document or website project.          
    serve           [input]             - Serve a Shiny interactive document.                        
    create-project  [dir]               - Create a project for rendering multiple documents          
    convert         <input>             - Convert documents to alternate representations.            
    pandoc          [args...]           - Run the version of Pandoc embedded within Quarto.          
    run             [script] [args...]  - Run a TypeScript, R, Python, or Lua script.                
    install         <type> [target]     - Installs an extension or global dependency.                
    publish         [provider] [path]   - Publish a document or project. Available providers include:
    check           [target]            - Verify correct functioning of Quarto installation.         
    help            [command]           - Show this help or the help of a sub-command.               

QuartoPub

• Vamos disponibilizar nossa apresentação no QuartoPub: https://quartopub.com/

• No terminal, usar o comando quarto publish quarto-pub nome-do-arquivo.qmd e seguir o passo a passo (no slide seguinte temos um exemplo).

/cloud/project$ quarto publish quarto-pub index.qmd
? Provider: › Quarto Pub
? Authorize (Y/n) › Yes
Please authorize by opening this url: https://quartopub.com/authorize?id=......
? Document name: › Use another name...
? Publish with name: › nome-da-apresentacao

[✓] Creating quarto-pub document
[✓] Preparing to publish document
[✓] Uploading files (complete)
[✓] Deploying published document
[✓] Published document: https://quartopub.com/sites/nome-usuario/nome-da-apresentacao
[✓] Account site updated: https://nome-usuario.quarto.pub

Vamos praticar!

Como alterar o estilo da apresentação?

Usando temas

• Existem alguns temas disponíveis para usar:

---
format: revealjs
---

Usando temas

• Existem alguns temas disponíveis para usar:

---
format:
  revealjs: 
    theme: moon
---

Temas disponíveis

• beige

• blood

• dark

• league

• moon

• night

• serif

• simple

• sky

• solarized

Tema padrão: default

Vamos praticar!

Personalizando o estilo

---
format:
  revealjs: 
    theme: moon
---

Personalizando o estilo

---
format:
  revealjs: 
    theme: [default, custom.scss]
---

Crie um arquivo custom.scss para adicionar novas regras de estilo por lá.

• Nesse arquivo teremos duas secões:

  • /*-- scss:defaults --*/ - SASS variables

  • /*-- scss:rules --*/ - regras em CSS

Copie o código de exemplo a seguir:

/*-- scss:defaults --*/

// importing fonts
@import url('https://fonts.googleapis.com/css2?family=Montserrat&family=Lato&display=swap');

// fonts
$font-family-sans-serif: 'Lato', Tahoma, sans-serif !default;

// headings
$presentation-heading-font: 'Montserrat',  Tahoma, sans-serif  !default;
$presentation-heading-color: #4c83b6 !default;


$body-bg: #191919;
$body-color: #fff;
$link-color: #42affa;

/*-- scss:rules --*/


.slide-logo {
  display: block !important;
  position: fixed !important;
  top: 0 !important;
  right: 10px !important;
  max-height: 15% !important;
  height: 100% !important;
  width: auto !important;
  color: $body-color !important;
}

.slide-number, .reveal.has-logo .slide-number {
  bottom: 10px !important;
  right: 10px !important;
  top: unset !important;
  color: $body-color !important;
}

Vamos praticar!

O que mais vocês desejam fazer nos slides?

Slide de exemplo e documentação

Onde aprender mais…

• Documentação do Quarto e a Galeria.

• Não falamos do Quarto
  Post em inglês por Alison Hill

• Reproducible Authoring with Quarto
  Apresentação em inglês por Mine Çetinkaya-Rundel

• Conteúdos sobre o Quarto na RStudio Conf 2022

• Workshop Get Started with Quarto

• Awesome Quarto