Markdown: Elementos Essenciais para Documentos do Sistema Quarto

Um tutorial simples sobre a linguagem de marcação Markdown para elaboração de documentos no sistema Quarto.

Autor

Afiliação

Prof. Dr. Washington S. da Silva

IFMG - Campus Formiga - Mestrado Profissional em Administração.

1 Introdução

Objetivos deste Tutorial

Este tutorial apresenta os elementos essenciais do Markdown para a criação de documentos no sistema Quarto. Ao final, você será capaz de:

• Criar documentos bem estruturados com Markdown
• Formatar textos com ênfases diferentes
• Inserir listas, links e imagens
• Incluir equações matemáticas simples
• Criar tabelas básicas

O que é Markdown?

Markdown é uma linguagem de marcação leve, criada para converter texto simples em documentos formatados. Principais vantagens:

• Simplicidade: Fácil de aprender e usar.
• Foco no conteúdo: Concentre-se no que escreve, não em como formatar.
• Flexibilidade: Funciona em diferentes plataformas.
• Conversão: Gera documentos em diversos formatos (html, pdf, docx).

2 Elementos Básicos do Markdown

2.1 Cabeçalhos

Os cabeçalhos são criados usando o símbolo #:

# Título Principal (H1)
## Subtítulo (H2)
### Seção (H3)
#### Subseção (H4)
##### Tópico (H5)
###### Subtópico (H6)

2.2 Parágrafos e Formatação de Texto

Em Markdown, os parágrafos são criados através de linhas em branco. Para iniciar um novo parágrafo, basta deixar uma linha vazia entre os blocos de texto.

Este é o primeiro parágrafo.

Este é o segundo parágrafo. Note a linha em branco 
entre eles.

Resultado:

Este é o primeiro parágrafo.

Este é o segundo parágrafo. Note a linha em branco entre eles.

Para criar uma quebra de linha sem iniciar um novo parágrafo (quebra de linha simples), adicione dois espaços no final da linha ou use a tag HTML <br>.

Esta linha termina com dois espaços  
e continua aqui na próxima linha.

Esta linha usa a tag HTML.<br>E continua aqui.

Resultado:

Esta linha termina com dois espaços
e continua aqui na próxima linha.

Esta linha usa a tag HTML.
E continua aqui.

2.3 Formatação de Texto

*Este texto será em itálico* e _este também_

**Este texto será em negrito** e __este também__

***Este texto será em negrito e itálico***

~~Este texto aparecerá riscado~~

`código inline` (útil para comandos, variáveis ou 
termos técnicos)

Resultado:

Este texto será em itálico e este também

Este texto será em negrito e este também

Este texto será em negrito e itálico

Este texto aparecerá tachado

código inline (útil para comandos, variáveis ou termos técnicos)

2.4 Blocos de Código

Para incluir blocos de código, use três crases (```) antes e depois do código:

```
Este é um bloco de código simples.
Preserva a formatação exata.
```

Resultado:

Este é um bloco de código simples.
Preserva a formatação exata.

2.4.1 Blocos de Código com Linguagem

Para destacar a sintaxe, especifique a linguagem:

```r
# Código em R
dados <- read.csv("arquivo.csv")
summary(dados)
```

```python
# Código em Python
import pandas as pd
df = pd.read_csv("arquivo.csv")
print(df.head())
```

```bash
# Comandos de terminal
git add .
git commit -m "Atualiza análise"
```

Resultado:

# Código em R
dados <- read.csv("arquivo.csv")
summary(dados)

# Código em Python
import pandas as pd
df = pd.read_csv("arquivo.csv")
print(df.head())

# Comandos de terminal
git add .
git commit -m "Atualiza análise"

2.5 Divisores Horizontais

Para criar uma linha divisória:

---

Resultado:

---

Útil para separar seções ou indicar mudanças de contexto.

2.6 Escape de Caracteres

Para usar caracteres especiais literalmente, use a barra invertida \:

\*Este texto não ficará em itálico\*
\# Este não será um cabeçalho
\[Este não será um link\]

Resultado:

*Este texto não ficará em itálico* # Este não será um cabeçalho [Este não será um link]

2.7 Listas

2.7.1 Listas Não-Ordenadas

- Primeiro item
- Segundo item
  - Subitem 2.1
  - Subitem 2.2
- Terceiro item

Resultado:

• Primeiro item
• Segundo item
  • Subitem 2.1
  • Subitem 2.2
• Terceiro item

Alternativas: asteriscos (*) e (+) também podem ser usados para criar listas não ordenadas.

2.7.2 Listas Ordenadas

1. Primeiro passo
2. Segundo passo
   1. Subtarefa 2.1
   2. Subtarefa 2.2
3. Terceiro passo

Resultado:

1. Primeiro passo
2. Segundo passo
   1. Subtarefa 2.1
   2. Subtarefa 2.2
3. Terceiro passo

2.7.3 Listas de Tarefas

- [x] Tarefa concluída
- [ ] Tarefa pendente
- [ ] Tarefa a fazer

Resultado:

• Tarefa concluída
• Tarefa pendente
• Tarefa a fazer

2.8 Links

2.8.1 Links Diretos

[Texto do link](https://www.exemplo.com)

Exemplo:

IFMG - Campus Formiga

2.8.2 Links de Referência

Para facilitar a leitura do código, você pode usar links de referência:

Este é um [link de referência][1] e este é [outro link][link-exemplo].

[1]: https://www.exemplo.com
[link-exemplo]: https://www.outrosite.com "Título opcional"

Resultado:

Este é um link de referência e este é outro link.

2.8.3 Links Automáticos

URLs e emails podem ser transformados automaticamente em links:

<https://www.exemplo.com>
<email@exemplo.com>

Resultado:

https://www.exemplo.com email@exemplo.com

2.9 Imagens

Para incluir imagens externas em seus documentos:

![Texto alternativo](img/imagem.jpg)

No Quarto, você pode adicionar atributos como largura e alinhamento:

![](imagens/foto.jpg){width=60% fig-align="center"}

3 Escrevendo matemática com LaTeX

LaTeX

LaTeX (pronuncia-se “Lah-tech” ou “Lay-tech”) é um sistema de preparação de documentos de alta qualidade, amplamente utilizado na academia, no mundo corporativo e em publicações científicas.

Desenvolvido por Leslie Lamport nos anos 1980, o LaTeX é uma extensão do sistema de composição tipográfica TeX, criado por Donald Knuth.

Diferentemente de processadores de texto tradicionais como Microsoft Word, o LaTeX funciona como uma linguagem de marcação, onde o autor escreve o conteúdo junto com comandos que definem a estrutura lógica e a formatação do documento. O sistema então processa esse código para gerar documentos com aparência profissional.

Características principais:

• Qualidade tipográfica superior: Especialmente para fórmulas matemáticas, equações e notações científicas complexas.

• Separação entre conteúdo e formatação: Permite ao autor focar no conteúdo enquanto o sistema gerencia a apresentação.

• Estabilidade e consistência: Mantém formatação uniforme através de documentos extensos.

• Referências cruzadas automatizadas: Facilita a criação e manutenção de citações, notas de rodapé e bibliografias.

• Extensibilidade: Através de pacotes adicionais que expandem suas funcionalidades

3.1 Integração com Markdown:

Muitos sistemas baseados em Markdown, incluindo o sistema Quarto, permitem a incorporação de expressões LaTeX diretamente no texto. Esta integração é especialmente útil para incluir equações matemáticas em documentos:

3.1.1 Expressões Matemáticas Inline

Use $...$ para inserir expressões matemáticas LaTeX em linha com o texto:

A fórmula da área do círculo é $A = \pi r^2$, 
sendo $r$ o raio.

Resultado:

A fórmula da área do círculo é A = \pi r^2, onde r é o raio.

3.1.2 Blocos de Equações

Use $$...$$ para equações em destaque:

A equação quadrática e sua solução:

$$
ax^2 + bx + c = 0
$$

$$
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

Resultado:

A equação quadrática e sua solução:

ax^2 + bx + c = 0

x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}

3.1.3 Exemplos de Expressões Matemáticas Úteis

Frações: 

$$
\frac{numerador}{denominador}
$$

Somatório: 

$$
\sum_{i=1}^{n} x_i
$$

Produtório: 

$$
\prod_{i=1}^{n} x_i
$$

Integral: 

$$
\int_{a}^{b} f(x) dx
$$

Limite: 

$$
\lim_{x \to \infty} f(x)
$$

Raiz quadrada: 

$$
\sqrt{x} \text{ e } \sqrt[n]{x}
$$

Subscritos e sobrescritos: 

$$
x_1, x_2, \ldots, x_n \text{ e } x^2, e^{-x}
$$

Resultado:

Frações:

\frac{numerador}{denominador}

Somatório:

\sum_{i=1}^{n} x_i

Produtório:

\prod_{i=1}^{n} x_i

Integral:

\int_{a}^{b} f(x) dx

Limite:

\lim_{x \to \infty} f(x)

Raiz quadrada:

\sqrt{x} \text{ e } \sqrt[n]{x}

Subscritos e sobrescritos:

x_1, x_2, \ldots, x_n \text{ e } x^2, e^{-x}

3.1.4 Equações Financeiras Comuns

Para estudantes de Administração, algumas equações úteis:

Valor Presente:

$$
VP = \frac{VF}{(1 + i)^n}
$$

Taxa de Retorno:

$$
ROI = \frac{Receita - Custo}{Custo} \times 100\%
$$

Média e Desvio Padrão:

$$
\bar{x} = \frac{1}{n}\sum_{i=1}^{n} x_i
$$

$$
s = \sqrt{\frac{1}{n-1}\sum_{i=1}^{n}(x_i - \bar{x})^2}
$$

Resultado:

Valor Presente:

VP = \frac{VF}{(1 + i)^n}

Taxa de Retorno:

ROI = \frac{Receita - Custo}{Custo} \times 100\%

Média e Desvio Padrão:

\bar{x} = \frac{1}{n}\sum_{i=1}^{n} x_i

s = \sqrt{\frac{1}{n-1}\sum_{i=1}^{n}(x_i - \bar{x})^2}

4 Tabelas

Tabelas em Markdown são criadas usando barras verticais e hífens:

| Produto   | Preço (R$) | Estoque |
|-----------|------------|---------|
| Produto A | 25,90      | 42      |
| Produto B | 15,50      | 38      |
| Produto C | 32,80      | 12      |

Resultado:

Produto	Preço (R$)	Estoque
Produto A	25,90	42
Produto B	15,50	38
Produto C	32,80	12

Alinhamento nas colunas:

| Produto   | Preço (R$) | Estoque |
|:----------|:----------:|---------:|
| Esquerda  | Centro     | Direita  |

5 Citações em Bloco

> Esta é uma citação em bloco.
> Continua na próxima linha.
>
> Este é um novo parágrafo na mesma citação.

Resultado:

Esta é uma citação em bloco. Continua na próxima linha.

Este é um novo parágrafo na mesma citação.

6 Elementos Especiais do Sistema Quarto

6.1 Callouts (Caixas de Destaque)

O Quarto oferece vários tipos de caixas para destacar informações.

Esses recursos funcionam perfeitamente para arquivos HTML e funcionam, mas não tão perfeitamente, em arquivos PDF produzidos pelo Typst.

::: {.callout-note}
## Nota

Uma informação importante a considerar.
:::

::: {.callout-tip}
## Dica

Uma sugestão para melhorar seu documento.
:::

::: {.callout-warning}
## Atenção

Um aviso para tomar cuidado.
:::

::: {.callout-important}
## Importante

Informação crítica que não deve ser ignorada.
:::

::: {.callout-caution}
## Cuidado

Um alerta sobre possíveis problemas.
:::

Resultado:

Nota

Uma informação importante a considerar.

Dica

Uma sugestão para melhorar seu documento.

Atenção

Um aviso para tomar cuidado.

Importante

Informação crítica que não deve ser ignorada.

Cuidado

Um alerta sobre possíveis problemas.

6.1.1 Callouts sem Ícones

::: {.callout-note icon="false"}
## Nota sem Ícone

Callout mais limpo, sem ícone.
:::

Nota sem Ícone

Callout mais limpo, sem ícone.

6.2 Referências Cruzadas (Cross-references)

O Quarto permite criar referências automáticas para figuras, tabelas e seções:

6.2.1 Referências para Figuras

![Logotipo do Markdown](img/markdown-hexsticker.png){#fig-logo width=30%}

Como visto na @fig-logo, o Markdown tem um logotipo distintivo.

6.2.2 Referências para Tabelas

| Produto | Preço | Estoque |
|---------|-------|---------|
| A       | 25,90 | 42      |
| B       | 15,50 | 38      |

: Dados de Produtos {#tbl-produtos}

A @tbl-produtos mostra os dados atualizados.

6.2.3 Referências para Seções

Como explicado na @sec-elementos, os elementos básicos são fundamentais.

6.3 Colunas (Layout)

O Quarto permite criar layouts de múltiplas colunas:

:::: {.columns}

::: {.column width="50%"}
**Coluna da Esquerda**

Conteúdo da primeira coluna.
:::

::: {.column width="50%"}
**Coluna da Direita**

Conteúdo da segunda coluna.
:::

::::

Resultado:

Coluna da Esquerda

Conteúdo da primeira coluna.

Coluna da Direita

Conteúdo da segunda coluna.

6.4 Abas (Tabset)

Para organizar conteúdo em abas:

::: {.panel-tabset}

## Aba 1

Conteúdo da primeira aba.

## Aba 2

Conteúdo da segunda aba.

:::

Resultado:

Aba 1

Conteúdo da primeira aba.

Aba 2

Conteúdo da segunda aba.

6.5 Destaque de Texto

Este texto contém uma [palavra destacada]{.mark}.

[Este texto está destacado como uma caixa]{.bg-warning}.

Resultado:

Este texto contém uma palavra destacada.

Este texto está destacado como uma caixa.

7 Exercícios Práticos

Exercício 1: Estrutura Básica

Crie um documento simples com:

1. Um título principal
2. Duas seções com subtítulos
   
3. Um parágrafo em cada seção
4. Uma lista de 3 itens
5. Um texto em negrito e outro em itálico

---

7.1 Exercício 2: Tabela e Links

1. Crie uma tabela com dados fictícios de vendas (produto, quantidade, valor)
2. Adicione um link para um site de sua escolha
3. Inclua uma equação matemática simples

---

7.2 Exercício 3: Elementos Avançados

1. Use pelo menos 2 tipos diferentes de callouts
2. Crie um bloco de código (pode ser R, Python, ou texto simples)
3. Adicione uma citação em bloco
4. Experimente com layout de colunas

Dica: Comece simples e vá adicionando elementos gradualmente!

8 Dicas Práticas

8.1 Organização de Arquivos

1. Seja consistente na estrutura e formatação.
2. Divida o conteúdo em seções lógicas.
3. Use cabeçalhos para criar uma hierarquia clara.
4. Mantenha imagens em uma pasta separada (img/) e organizada.
5. Nomeie arquivos de forma descritiva: relatorio-vendas-2024.qmd

8.2 Fluxo de Trabalho

1. Revise a visualização do documento regularmente.
2. Aprenda gradualmente - comece com os elementos básicos.
3. Use preview do RStudio ou VS Code para ver resultados em tempo real.
4. Salve frequentemente e use controle de versão (Git).

8.3 Formatação e Estilo

1. Evite overformatação - o Markdown é sobre simplicidade.
2. Use espaços em branco para melhorar a legibilidade do código.
3. Seja consistente com a escolha de símbolos (*, -, _ etc.).
4. Teste em diferentes formatos de saída (HTML, PDF).

8.4 Resolução de Problemas Comuns

8.4.1 Quebras de Linha não Funcionam

• Lembre-se: duas linhas em branco criam novo parágrafo
• Use dois espaços + Enter para quebra simples
• Ou use <br> quando necessário

8.4.2 Caracteres Especiais

• Use \ para escapar caracteres: \*, \#, \[
• Em equações, use \{ e \} para chaves literais

8.4.3 Tabelas não Alinham

• Certifique-se de que todas as linhas têm o mesmo número de colunas
• Use espaços para alinhar visualmente no código
• Teste com conteúdo simples primeiro

9 Recursos Adicionais

9.1 Documentação Oficial

• Quarto - Markdown Basics
• Quarto - Cross References
• Pandoc Markdown

9.2 Ferramentas Úteis

9.2.1 Editores com Suporte ao Markdown

• RStudio: Excelente integração com Quarto
• VS Code: Com extensões Quarto e Markdown
• Typora: Editor WYSIWYG para Markdown
• Mark Text: Editor focado em Markdown

9.2.2 Geradores de Tabelas

• Gerador de Tabelas
• Gerador de Tabelas Markdown

9.2.3 Referência Rápida

• Guia Rápido de Markdown
• Símbolos Matemáticos LaTeX

9.3 Próximos Passos

Após dominar este conteúdo, considere aprender:

1. Bibliografia com Quarto: Citações e referências automáticas
2. Parâmetros de documento: Documentos dinâmicos e reproduzíveis
3. Extensões do Quarto: Filtros e funcionalidades avançadas
4. Integração com R/Python: Documentos com código executável

Lembre-se

O Markdown é uma ferramenta poderosa justamente por sua simplicidade. Comece com o básico e vá adicionando complexidade conforme sua necessidade. O importante é criar documentos claros, bem estruturados e reproduzíveis.

10 Conclusão

Markdown é uma linguagem simples e poderosa para criar documentos no sistema Quarto. Com este tutorial básico, você já pode começar a escrever documentos bem formatados, adicionando posteriormente elementos mais avançados conforme sua necessidade e familiaridade com a linguagem e com o sistema Quarto.

11 Glossário de Termos

C

Callout: Elemento visual do Quarto usado para destacar informações importantes, dicas, avisos ou notas em caixas coloridas e formatadas.

Referência Cruzada: Sistema de referências cruzadas que permite criar links automáticos para figuras, tabelas, seções e equações dentro do documento.

H

HTML: HyperText Markup Language - linguagem de marcação padrão para criar páginas web. O Markdown pode ser convertido para HTML.

L

LaTeX: Sistema de preparação de documentos amplamente usado para documentos científicos, especialmente eficaz para equações matemáticas complexas.

Linguagem de Marcação: Sistema de anotações inseridas em um texto para definir como ele deve ser estruturado, formatado ou apresentado. Ao contrário das linguagens de programação que executam comandos, as linguagens de marcação utilizam tags ou comandos para identificar elementos do documento (como títulos, parágrafos, listas) sem se preocupar com a lógica computacional. Exemplos incluem HTML (para páginas web), XML (para dados estruturados), LaTeX (para documentos científicos) e Markdown (usada no Quarto para formatação simplificada de texto).

M

Markdown: Linguagem de marcação leve criada por John Gruber em 2004, projetada para ser fácil de ler e escrever, convertendo texto simples em HTML estruturado.

P

Pandoc: Conversor universal de documentos que traduz entre diferentes formatos de marcação. É a base do sistema Quarto para conversão de documentos.

Q

Quarto: Sistema de publicação científica e técnica de código aberto baseado em Pandoc, sucessor do R Markdown, que suporta múltiplas linguagens de programação.

R

Renderização: Processo de conversão do documento Markdown/Quarto para o formato final (HTML, PDF, Word, etc.).

Reprodutibilidade: Capacidade de reproduzir exatamente os mesmos resultados ao executar novamente uma análise ou processo de criação de documento.

S

Destaque de Sintaxe: Funcionalidade que colore e formata código de acordo com a linguagem de programação especificada, facilitando a leitura.

Y

YAML: Yet Another Markup Language - formato de serialização de dados usado no cabeçalho dos documentos Quarto para configurar metadados e opções de renderização.