1 Breve histórico
Tradução e adaptação do prefácio do livro R Markdown: The Definitive Guide, de Yihui Xie, J. J. Allaire, Garrett Grolemund.
Markdown foi criado por John Gruber e Aaron Swartz em 2004. A versão original costumava ser considerada excessivamente simples e inadequada para escrever documentos altamente técnicos. Por exemplo, não havia sintaxe para tabelas, notas de rodapé, expressões matemáticas ou citações. Em 2006, John MacFarlane criou um conversor de documentos extremamente útil, denominado Pandoc, capaz de converter documentos Markdown em uma grande variedade de formatos de saída (HTML, LaTeX/PDF, entre outros). Assim, a importância de Markdown foi significativamente enriquecida. O formato de documento R Markdown foi introduzido pela primeira vez por Yihui Xie, no pacote R knitr, em 2012. A ideia foi incorporar blocos de código de programação (de R ou outras linguagens) em documentos Markdown. Em 2014, o pacote R rmarkdown foi criado. De lá para cá, uma equipe de colaboradores (Allaire, McPherson, Yihui Xie, et al.) vem contribuindo na manutenção desse pacote.
R Markdown utiliza as facilidades do Markdown nativo para tornar possível fazer: parágrafos, cabeçalhos de seção, citações de bloco, blocos de código, listas numeradas e não numeradas, tabelas, expressões matemáticas LaTeX, links, imagens, notas de rodapé, referências bibliográficas, entre outros recursos.
O que vamos apreciar usando R Markdown é que nossos resultados de computação terão maior probabilidade de ser recriados e reformulados, em comparação com a abordagem manual de recortar e colar. Isso ocorre porque os resultados são gerados dinamicamente a partir do código-fonte do computador. Se algo der errado ou precisar ser atualizado, podemos simplesmente corrigir ou atualizar o código-fonte, compilar o documento novamente e os resultados serão automaticamente atualizados: para alguns, algo inacreditável, para nós, algo natural, cômodo e divertido.
2 Instalação, YAML e Renderização
A instalação e o carregamento são feitos pelos comandos:
install.packages("rmarkdown")
library(rmarkdown)
A seção YAML contém as variáveis que vão configurar o aspécto final do documento:
---
title: "Treino com R Markdown"
subtitle: "Edição de Documentos"
author: "Cássio Sanguini Sergio"
date: "02/05/2021"
bibliography: [bibliography.bib]
biblio-style: apalike
link-citations: TRUE
output:
html_document:
css: styleMD.css
toc: TRUE
number_sections: TRUE
keep_md: TRUE
pdf_document:
toc: TRUE
toc_depth: 2
keep_tex: TRUE
latex_engine: xelatex
citation_package: natbib
documentclass: article # opções LaTeX/PDF
classoption: oneside
papersize: a4
geometry: margin = 1in
fontsize: 12pt
linestretch: 1.5
linkcolor: blue
lang: pt-BR
---
A renderização do primeiro output definido na seção YAML,
é feita simplesmente utilizando o nome do arquivo de trabalho:
rmarkdown::render("treino_com_markdown.Rmd").
Já a renderização de outro output, precisa ser especificada:
rmarkdown::render("treino_com_markdown.Rmd", "pdf_document").
O usuário escreve seu documento em um arquivo do tipo R Markdown (.Rmd). O processo de renderização é executado automaticamente pelo pacote rmarkdown. Inicialmente, o pacote knitr processa o arquivo de entrada (.Rmd) e devolve um arquivo de saída Markdown (.md). Em seguida, o arquivo.md é transformado em um documento HTML ou PDF, pelo conversor de documentos Pandoc.
Nota: Após a renderização, pode-se manter uma cópia do arquivo.md, usando a opção: keep_md: true.
Ver mais informações.
3 Disparos HTML de marcações R Markdown
Estão disponíveis na internet diversos tutoriais sobre R Markdown. Aqui vamos apresentar algumas marcações significativas da linguagem e mostrar os elementos html que geram a página html. Caso queira se aprofundar, a melhor opção é consultar o livro R Markdown: The Definitive Guide.
3.1 Parágrafos
Em Rmd, há possibilidade de começar um novo parágrafo colocando mais que 2 espaços ao final da linha. Por exemplo, a marcação abaixo:
Terminando com 0 espaço.
Terminando com 1 espaço.
Agora, terminando está linha com 2 espaços.
"Fui jogado para baixo".Resulta em:
Terminando com 0 espaço.
Terminando com 1 espaço.
Agora, terminando está linha com 2 espaços.
“Fui jogado para baixo.”
Agora vamos ver o código que gera a página html:
<p>
Terminando com 0 espaço.
Terminando com 1 espaço.
Agora, terminando está linha com 2 espaços. <br />
"Fui jogado para baixo".
</p>Como é de se esperar, o código acima também resulta em:
Terminando com 0 espaço.
Terminando com 1 espaço.
Agora, terminando está linha com 2 espaços.
“Fui jogado para baixo.”
3.2 Letras italic and bold
Colocando ênfase.
Colocando forte.
Colocando os dois, ênfase e forte.
– Rmd –
Colocando _ênfase_.
Colocando __forte__.
Colocando os dois, ___ênfase e forte___.– html –
Colocando <em>ênfase</em>.
Colocando <strong>forte</strong>.
Colocando os dois, <strong><em>ênfase e forte</em></strong>.3.3 Elementos pre e code
Um backtick
A marcação Rmd entre backticks é um recurso útil e fácil de usar.
Ela dispara na linha do texto (não em bloco). Por exemplo,
Coloque isso em marcação backticks, é feito assim:
`Coloque isso em marcação backticks`.
O equivalente html é:
<p><code>Coloque isso em marcação p code.</code></p>
Visto que um backtick dispara o parágrafo <p><code></code></p>, o estilo dessa marcação é modificado pelo seletor css p code {}, conforme abaixo:
p code {
font-size : 0.85em;
color : crimson; /* vermelho */
background-color : #F1F1F1; /* cinza claro */
padding : 0px;
}
Três backticks
Escrever entre 3 backticks dispara um bloco com bordas e cor de fundo, que tem a característica de preservar os espaços em branco e criar uma barra de rolagem.
Por exemplo:
``` Coloque isso entre 3 backticks. ```
Resulta em:
Coloque isso entre 3 backticks.Mas, se a linha for muito longa, resulta em:
Coloque isso entre 3 backticks.O equivalente html é:
<pre><code> Coloque isso entre pre code. </code></pre>
Vamos fazer um teste: Retirar o elemento <code> da estrutura acima, e deixar somente o elemento <pre>, desse jeito:
<pre> Coloque isso em marcação pre (somente). </pre>
Agora, veja o resultado:
Coloque isso em marcação pre (somente).
O sombreado verde claro sumiu! Isso por que há um seletor css que controlo o elemento <pre> (sozinho) e outro que controla o elemento <code> que está dentro de um elemento <pre>, escrito como <pre><code>.
O elemento <pre> (sozinho) é controlado pelo seletor pre:not([class]) {}, que significa, <pre> sem atributo de classe:
pre:not([class]) {
font-family : monospace;
font-size : 0.65em;
color : black;
background-color : #f9f9f9; /* cinza claro */
border : 2px solid #c9c9c9; /* cinza */
max-width : 100%;
padding : 1.6em 1.6em;
margin-bottom : 1.6em;
margin-bottom : 1.6em;
}
Por outro lado, o elemento <code> dentro do elemento <pre>, é controlado pelo seletor pre:not([class]) code {}:
pre:not([class]) code {
word-wrap : normal;
white-space : pre;
background-color : #e6ffe6; /* verde claro */
}
Vamos, então, fazer outro teste, atribuir uma classe ao elemento <pre>:
<pre class = "aumentar"> Coloque isso em marcação pre e adicione uma classe. </pre>
Sendo a classe definida como:
<style> .aumentar {
font-size : 24px;
font-weight : bold;
text-align : center;
color : #99ffcc; /* verde */
background-color : black;
border : 6px solid red;
} </style>
Resultado:
Coloque isso em marcação pre e adicione uma classe.
Como esperado, o procedimento acima anulou a atuação do seletor pre:not([class]) {}.
Por fim, vamos atribuir um estilo ao elemento <pre>:
<pre style = "background-color: yellow;"> Coloque isso em marcação pre e adicione um estilo. </pre>
Resultado:
Coloque isso em marcação pre e adicione um estilo.
Nesse último caso, não se anulou o seletor pre:not([class]) {}, apenas ocorreu a substituição da cor de fundo, de cinza claro, para amarelo berrante.
Resumo:
O mais importante para nós que vamos fazer uso da marcação Rmd, é entender que 3 backticks dispara um bloco <pre><code> …disparo… </code></pre>, controlado por 2 seletores: pre:not([class]) {} e pre code {}; e que 1 backtick, dispara um parágrafo <p><code> …disparo… </code></p>, controlado pelo seletor p code {}.
3.4 Barra blockquote
Um jacaré.
Dois jacarés.
Três jacarés.
– Rmd –
> Um jacaré.
>> Dois jacarés.
>>> Três jacarés.– html –
<blockquote>
<p>Um jacaré.</p>
</blockquote>
<blockquote>
<blockquote>
<p>Dois jacarés.</p>
</blockquote>
</blockquote>
<blockquote>
<blockquote>
<blockquote>
<p>Três jacarés.</p>
</blockquote>
</blockquote>
</blockquote>3.5 Listas com objetos
- Folhas;
- Cadernos;
- Canetas;
- Borrachas.
– Rmd –
* Folhas;
* Cadernos;
* Canetas;
* Borrachas.– html –
<ul>
<li>Folhas;</li>
<li>Cadernos;</li>
<li>Canetas;</li>
<li>Borrachas.</li>
</ul>- Folhas;
- Cadernos;
- Canetas;
- Borrachas.
– Rmd –
a. Folhas;
b. Cadernos;
c. Canetas;
d. Borrachas.– html –
<ol style="list-style-type: lower-alpha">
<li>Folhas;</li>
<li>Cadernos;</li>
<li>Canetas;</li>
<li>Borrachas.</li>
</ol>- Folhas;
- Cadernos;
- Canetas;
- Borrachas.
– Rmd –
i. Folhas;
ii. Cadernos;
iii. Canetas;
iv. Borrachas.– html –
<ol style="list-style-type: lower-roman">
<li>Folhas;</li>
<li>Cadernos;</li>
<li>Canetas;</li>
<li>Borrachas.</li>
</ol>3.6 Link de site
– Rmd –
Faça uma visita em nosso site: bycfisica.
[bycfisica](https://bycfisica.netlify.app/ "bycfisica").Jeito rápido de fazer: https://bycfisica.netlify.app/
<https://bycfisica.netlify.app/>Jeito ultra-rápido de fazer: https://bycfisica.netlify.app/
https://bycfisica.netlify.app/– html –
Se você deseja que o usuário abra seu link em uma nova guia, então faça: https://bycfisica.netlify.app/
<a href="https://bycfisica.netlify.app/"
target="_blank" title="bycfisica">https://bycfisica.netlify.app/</a>4 Imagens
Vamos adicionar uma imagem usando a marcação Rmd.
Como estão se saindo?
Agora, a mesma imagem adicionada com elementos html.
<div class="figure">
<img src="img/my3dogs.png" style="width:50%">
<p class="caption">Tem cheiro de que estão gostando!</p>
</div>Tem cheiro de que estão gostando!
Por fim, o pacote R knitr possue recursos avançados para se adicionar imagens em documentos. Abaixo está o código-fonte para se adicionar a mesma imagem.
```{r LK1, echo=F, message=F, warning=F, fig.cap="Nós também estamos au au au... mando!",out.width="50%",fig.align="center"}
knitr::include_graphics("img/my3dogs.png", error = FALSE)
```Figura 4.1: Nós também estamos au au au… mando!
LIMITAÇÃO: A renderização feita com rmarkdown não dispara figuras com numeração automática.
Nota: Para gerar este site, a renderização foi feita com blogdown, por isso apareceu a numeração da figura acima.
5 Código de programação
R Markdown foi projetado para uma reprodutibilidade mais fácil, uma vez que o código de programação e as narrativas estão no mesmo documento. Abaixo temos o que é chamado de código “chunk.” Para realizar a tarefa, o pacote R knitr faz a compilação, primeiro, extraindo e executando o código que está dentro do “chunk” e, em seguida, disparando o resultado junto com o texto que se encontra ao redor.
```{r LK2, echo=F, message=F, warning=F, fig.cap="Uma parábola.",out.width="70%",fig.align="center"}
library(tidyverse)
x <- seq(-50,50)
y <- x^{2}
tb <- tibble(x,y)
p <- ggplot(tb, aes(x,y)) + geom_point(color="yellow") + theme_dark()
print(p)
```
Figura 5.1: Uma parábola.
O valor no ponto x[17] é y[17]
(isso é blockquote).
o valor no ponto `x[17]` é `y[17]`.
(isso é blockquote)O valor no ponto -34 é 1156 (isso é resultado de “chunk,” disparado na linha do texto)
O valor no ponto ` r x[17] ` é ` r y[17] `.
(isso é resultado de "chunk", disparado na linha do texto)Por fim, quer alterar a aparência do “chunk?” Acesse aqui.
Vamos ver um exemplo quando o código é muito longo e deseja-se economizar espaço no navegador
criando uma barra de rolagem vertical.
Primeiro, cria-se um css persolalizado (observem o baixo valor à variável max-height).
Em seguida, usa-se esse css na variável class.source do “chunk”:
```{css, echo=F, message=F, warning=F}
.MEUCSS {
background-color : #e6ffe6;
border : 4px solid #7D8D69;
font-weight : bold;
font-size : 14px;
max-height : 150px;
}
```
```{r class.source="MEUCSS", eval=F}
--------------------------------------------------------
AGLOMERADOS COM 4 ÁTOMOS
Si 4 3 2 1 0
Al 0 1 2 3 4
Al(%) 0 0.25 0.50 0.75 1
--------------------------------------------------------
----------------------------------------------------------------------
AGLOMERADOS COM 6 ÁTOMOS
Si 6 5 4 3 2 1 0
Al 0 1 2 3 4 5 6
Al(%) 0 0.17 0.33 0.50 0.67 0.83 1
----------------------------------------------------------------------
------------------------------------------------------------------------------------
AGLOMERADOS COM 8 ÁTOMOS
Si 8 7 6 5 4 3 2 1 0
Al 0 1 2 3 4 5 6 7 8
Al(%) 0 0.13 0.25 0.38 0.50 0.63 0.75 0.88 1
------------------------------------------------------------------------------------
--------------------------------------------------------------------------------------------------
AGLOMERADOS COM 10 ÁTOMOS
Si 10 9 8 7 6 5 4 3 2 1 0
Al 0 1 2 3 4 5 6 7 8 9 10
Al(%) 0 0.10 0.20 0.30 0.40 0.50 0.60 0.70 0.80 0.90 1
--------------------------------------------------------------------------------------------------
```Confira o resultado:
--------------------------------------------------------
AGLOMERADOS COM 4 ÁTOMOS
Si 4 3 2 1 0
Al 0 1 2 3 4
Al(%) 0 0.25 0.50 0.75 1
--------------------------------------------------------
----------------------------------------------------------------------
AGLOMERADOS COM 6 ÁTOMOS
Si 6 5 4 3 2 1 0
Al 0 1 2 3 4 5 6
Al(%) 0 0.17 0.33 0.50 0.67 0.83 1
----------------------------------------------------------------------
------------------------------------------------------------------------------------
AGLOMERADOS COM 8 ÁTOMOS
Si 8 7 6 5 4 3 2 1 0
Al 0 1 2 3 4 5 6 7 8
Al(%) 0 0.13 0.25 0.38 0.50 0.63 0.75 0.88 1
------------------------------------------------------------------------------------
--------------------------------------------------------------------------------------------------
AGLOMERADOS COM 10 ÁTOMOS
Si 10 9 8 7 6 5 4 3 2 1 0
Al 0 1 2 3 4 5 6 7 8 9 10
Al(%) 0 0.10 0.20 0.30 0.40 0.50 0.60 0.70 0.80 0.90 1
--------------------------------------------------------------------------------------------------6 Tabelas
Vamos ver uma tabela usando a marcação Rmd.
| Cabeça 1 | Cabeça 2 | Cabeça 3 |
|---|---|---|
| Linha 1 | célula | célula com muitas palavras |
| Linha 2 | célula | célula |
| Linha 3 | célula que se estende por duas colunas | |
| Linha 4 | célula | célula |
| Cabeça 1 | Cabeça 2 | Cabeça 3 |
| :---------- | :---------: | ----------: |
| Linha 1 | célula | célula com muitas palavras |
| Linha 2 | célula | célula |
| Linha 3 | célula que se estende por duas colunas ||
| Linha 4 | célula | célula |
Table: A legenda fica aqui.A mesma tabela com elementos html:
<table>
<caption>A legenda fica aqui.</caption>
<thead>
<tr class="header">
<th align="left">Cabeça 1</th>
<th align="center">Cabeça 2</th>
<th align="right">Cabeça 3</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td align="left">Linha 1</td>
<td align="center">célula</td>
<td align="right">célula com muitas palavras</td>
</tr>
<tr class="even">
<td align="left">Linha 2</td>
<td align="center">célula</td>
<td align="right">célula</td>
</tr>
<tr class="odd">
<td align="left">Linha 3</td>
<td align="center">célula que se estende por duas colunas</td>
<td align="right"></td>
</tr>
<tr class="even">
<td align="left">Linha 4</td>
<td align="center">célula</td>
<td align="right">célula</td>
</tr>
</tbody>
</table>Por fim, os pacotes R knitr::kable e kableExtra possuem recursos avançados para fazer tabelas incríveis. Abaixo está o código-fonte de uma tabela com casas e cabeçalhos.
```{r LK3, echo=F, message=F, warning=F}
library(tidyverse)
library(kableExtra)
C1 <- c("casa 1.I","casa 2.I","casa 3.I","casa 4.I")
C2 <- c("casa 1.II","casa 2.II","casa 3.II","casa 4.II")
C3 <- c("casa 1.III","casa 2.III","casa 3.III","casa 4.III")
tb <- tibble(C1, C2, C3)
tb %>% rename(`Cabeçalho I`=C1, `Cabeçalho II`=C2, `Cabeçalho III`=C3) %>%
kbl(booktabs=T, align = "lcc", caption="A legenda escreve aqui.") %>%
kable_styling(bootstrap_options="striped")
```| Cabeçalho I | Cabeçalho II | Cabeçalho III |
|---|---|---|
| casa 1.I | casa 1.II | casa 1.III |
| casa 2.I | casa 2.II | casa 2.III |
| casa 3.I | casa 3.II | casa 3.III |
| casa 4.I | casa 4.II | casa 4.III |
| casa 5.I | casa 5.II | casa 5.III |
LIMITAÇÃO: A renderização feita com rmarkdown não dispara tabelas com numeração automática.
Nota: Para gerar este site, a renderização foi feita com blogdown, por isso apareceu a numeração da tabela acima.
7 Notas de rodapé e referências
Aqui temos um exemplo de com se fazer um nota de rodapé.1
Aqui temos um exemplo de com se fazer um nota de rodapé. [^1]
[^1]: Mais uma facilidade do pacote R bookdown.Bookdown usa a mesma estrutura de documentos R Markdown para citar as referências. Veja alguns exemplos: (Mosca 1974), (Bransden 2000), (Dionisio 2007) e (Griffiths 2016).
Bookdown usa a mesma estrutura de documentos R Markdown para citar as referências.
Veja alguns exemplos: [@mosca1974], [@Bransden], [@PHD2007] e [@Griffiths].Os detalhes das referências, como título, autor, revista, etc, além do nome do link, ficam armazenados no arquivo de referências bibliography.bib:
@Book{mosca1974,
title = {Magnetic Forces Doing Work?},
author = {Eugene P. Mosca},
year = {1974},
publisher = {American Journal of Physics, Volume 42, Pages 295-297}
}
@Book{Joachain,
title = {Quantum Mechanics},
author = {B.H. Bransden, C.J. Joachain},
publisher = {Pearson Education, ISBN 978-8131708392},
year = {2000},
edition = {2nd},
}
@Book{PHD2007,
title = {Esta Esquecida Força Eletromotriz de Movimento},
author = {Paulo Henrique Dionisio},
year = {2007},
publisher = {Revista Brasileira de Ensino de Física, Vol. 29}
}
@Book{Griffiths,
title = {Introduction to Quantum Mechanics},
author = {David J. Griffiths},
publisher = {Cambridge University Press, ISBN 978-1107179868},
year = {2016},
edition = {2nd},
}8 Como saber onde mexer
As vezes desejamos alterar um aspécto de nosso documento, mas não sabemos onde mexer.
A dica é usar o recurso Ver código-fonte da página, clicando com o botão direito do mouse.
Por exemplo, parte do código-fonte da página deste documento apresenta os seguines elementos html:
<div id="header">
<h1 class="title">Treino com R Markdown</h1>
</div>Como se vê, o título do documento é gerado pelo elemento <h1></h1>, modificado pela classe title.
Então, para controlar o título, deve-se criar o seletor h1.title {} no arquivo css.
Veja como fazer para a cor de fundo do título ser
vermelho google:
h1.title {
background-color: #EA4335;
}Referências
Mais uma facilidade do pacote R bookdown.↩︎