9.1 Markdown

Se você é uma pessoa que utiliza R, sabe das possibilidades de utilizar R Markdown (e os pacotes que expandem mais ainda as possibilidades) e gostaria de começar a utilizá-lo, é importante conhecer o Markdown. Por quê? O R Markdown tem como base a linguagem de marcação Markdown.

Os arquivos markdown podem ser abertos por qualquer software que suporte este formato aberto. Além disso, independente da plataforma de trabalho, pode-se migrar para um arquivo de texto sem perder a formatação. O Markdown também é usado em outros lugares, como no GitHub e no Fórum da Curso-R.

Uma referência interessante para ter sempre em mãos é a Folha de cola (Cheatsheet) do Markdown.

Nas seções seguintes, descreveremos como podemos marcar os nossos textos e códigos usando markdown, e você poderá usar isso tanto em arquivos .Rmd, quanto em outros lugares que também utilizam essa marcação (como no Fórum da Curso-R!).

9.1.1 Ênfase

Negrito

Para destacar um texto em negrito, coloque ** ou __ ao redor do texto.

Por exemplo:

Como é escrito no código Como aparece no relatório
Esse é um texto com uma palavra destacada em **negrito**. Esse é um texto com uma palavra destacada em negrito.
Esse é um texto com uma palavra destacada em __negrito__. Esse é um texto com uma palavra destacada em negrito.

Itálico

Para destacar um texto em itálico, coloque * ou _ ao redor do texto.

Por exemplo:

Como é escrito no código Como aparece no relatório
Esse é um texto com uma palavra destacada em *itálico*. Esse é um texto com uma palavra destacada em itálico.
Esse é um texto com uma palavra destacada em _itálico_. Esse é um texto com uma palavra destacada em itálico.

Riscado (ou tachado)

Para riscar/tachar um texto, coloque ~~ ao redor do texto.

Por exemplo:

Esse é um texto com uma palavra riscada/tachada.

Como é escrito no código Como aparece no relatório
Esse é um texto com uma palavra ~~riscada/tachada~~. Esse é um texto com uma palavra riscada/tachada.

9.1.2 Títulos

Os títulos funcionam como uma hierarquia, e para criar um título é necessário colocar um # no início da linha. Então um # marca um título, ## marca um sub-título, e assim sucessivamente. Veja os exemplos:

Como é escrito no código Como aparece no relatório
# Título 1
## Título 2
### Título 3

9.1.3 Listas

Listas ordenadas

Você pode fazer uma lista ordenada usando somente números. Você pode repetir o número quantas vezes quiser:

Como é escrito no código:

1. Maçã

1. Banana

1. Uva

Como aparece no relatório:

  1. Maçã
  2. Banana
  3. Uva

Listas não ordenadas

Você pode fazer uma lista não ordenada escrevendo com hífens ou asteriscos, como a seguir:

* Maçã

* Banana

* Uva

- Maçã

- Banana

- Uva

O resultado será:

  • Maçã
  • Banana
  • Uva

Você também pode adicionar sub-itens na lista indicando a hierarquia através da identação no Markdown (dica: utilize a tecla tab do teclado):

  • Frutas
    • Maçã
    • Banana
    • Uva

9.1.4 Equações

Você pode adicionar equações utilizando LaTeX. Você pode saber mais na página do Overleaf sobre expressões matemáticas. Além disso, existem geradores de equações online que ajudam a escrevâ-las em LaTeX, HTML, entre outras linguagens de marcação.

É possível centralizar a equação envolvendo o código com $$. Veja o exemplo abaixo:

Como é escrito no código Como aparece no relatório
$$y = \mu + \sum_{i=1}^p \beta_i x_i + \epsilon$$ \[y = \mu + \sum_{i=1}^p \beta_i x_i + \epsilon\]

Também é possível adicionar a equação na mesma linha que o texto, envolvendo o código com $. Veja o exemplo abaixo:

Como é escrito no código Como aparece no relatório
Ou também na linha $y = \mu + \sum_{i=1}^p \beta_i x_i + \epsilon$ , junto ao texto! Ou também na linha \(y = \mu + \sum_{i=1}^p \beta_i x_i + \epsilon\) , junto ao texto!

9.1.5 Código

É possível marcar textos para que fiquem formatados como códigos, usando a crase: `

Mas atenção: o texto será formatado como código, porém não será executado!

Como é escrito no código Como aparece no relatório
`mean(pinguins$massa_corporal, na.rm = TRUE)` mean(pinguins$massa_corporal, na.rm = TRUE)

Também é possível delimitar um trecho maior de código, utilizando três crases.

Exemplo:

Como é escrito no código:

```
library(dados)
mean(pinguins$massa_corporal, na.rm = TRUE)
```

Como aparece no relatório:

library(dados)
mean(pinguins$massa_corporal, na.rm = TRUE)

9.1.7 Imagens

Você pode incluir uma imagem utilizando esta estrutura:

![descricao da imagem](http://url-da-imagem.com).

Não se esqueça: a descrição da imagem é importante para acessibilidade do conteúdo através de leitores de tela!

Como é escrito no código Como aparece no relatório
![Logo da Curso-R](assets/img/relatorios/logo_cursor_full.png) Logo da Curso-R

9.1.8 Tabelas

As tabelas em Markdown têm uma estrutura definida, como mostra o exemplo abaixo.

É possível usar ferramentas online para gerar tabelas em Markdown, como por exemplo o Tables Generator.

Em Markdown:

|  a|  b|  c|
|--:|--:|--:|
|  1|  2|  3|
|  2|  3|  4|

Resultado:

a b c
1 2 3
2 3 4

9.1.9 Recapitulando

Nesta seção, aprendemos que o Markdown é uma linguagem de marcação, usada para marcar textos. Podemos usar o Markdown para formatar textos e adicionar elementos no nossos relatórios.

Porém existem elementos (como código, imagens, tabelas, entre outros) que podemos também adiconar nos relatórios utilizando R. É isso que veremos na seção seguinte!

Exercícios

1. Leia a primeira página o guia de referência do RMarkdown

2. Liste abaixo outros lugares que utilizam o Markdown como base (Dica: outras linguagens de programação, fóruns, aplicativos de mensagem, etc)

3. Qual é o output se você criar uma lista ordenada começando no 2? Por exemplo:

2. primeiro item

2. segundo item

2. terceiro item

4. O que são os sabores de Markdown (Markdown flavor)?

5. Experimente o pandoc no site de demonstração da ferramenta.

Curso-R