# Escrever em Markdown

Rascunhe com o Markdown familiar e produza um PDF ou um documento editável para colaboradores.

O Markdown funciona bem para notas de pesquisa, relatórios e rascunhos iniciais. O Oleafly dá a ele uma barra de formatação dedicada e um caminho de compilação com Pandoc, com arquivos-fonte que você pode usar fora do aplicativo.

## Faça um relatório

1. Escolha **Novo projeto → Usar um modelo → Documento Markdown em branco**.
2. Dê ao projeto o nome **Notas de campo** e abra `main.md`.
3. Cole este exemplo e escolha **Compilar de novo** ou pressione **⌘Enter / Ctrl+Enter**.
4. Se o Oleafly oferecer configurar um motor necessário, conclua essa configuração e compile de novo.

```markdown title="main.md"
---
title: "Field notes"
author: "Alex Chen"
date: ""
---

# Question

Does the revised procedure reduce measurement time?

## Method

1. Prepare the sample.
2. Repeat the measurement three times.
3. Record the elapsed time.

## Observations

| Run | Time (s) | Note |
| --- | --- | --- |
| 1 | 12 | First pass |
| 2 | 10 | Repeated pass |

The **mean time** will be compared with the baseline.
```

O PDF deve incluir um título, títulos de seção, uma lista numerada e uma tabela. Os metadados entre o primeiro par de linhas `---` controlam o título e o autor do documento.

## Tipos de documento

Adicione uma linha `type` ao front matter para compilar o documento como um relatório, um livro, slides, um pôster, uma carta ou um currículo. Sem `type`, ou com um valor que o Oleafly não conhece, o documento é compilado como um artigo.

| `type` | O que compila | Preenchido, a menos que você defina |
| --- | --- | --- |
| `article` | Um artigo | Nada |
| `report` ou `thesis` | Um relatório, com um capítulo em cada título `#` | `documentclass: report` |
| `book` | Um livro, com um capítulo em cada título `#` | `documentclass: book` |
| `slides` | Slides Beamer 16:9. Um título `#` inicia uma seção e um título `##` inicia um slide | `aspectratio: 169` |
| `poster` | Um pôster Beamer de uma página, encabeçado por `title`, `subtitle`, `author` e `institute` | Papel A0, retrato |
| `letter` | Uma carta com o seu endereço e o do destinatário, uma linha de assunto, uma saudação e um fecho | `documentclass: scrlttr2` |
| `cv` | Um artigo compacto | `geometry: margin=2cm` e `pagestyle: empty` |

O seu próprio front matter vence. Um valor que você define, como `documentclass`, `aspectratio` ou `geometry`, substitui o que o tipo preenche.

Para slides, defina `slide-level` para escolher o nível de título que inicia um slide. Com `slide-level: 1`, todo título `#` inicia um. Os slides são compilados como um PDF comum, então **Apresentar**, na barra de ferramentas da prévia, pode mostrá-los. Veja [Apresentar slides](/docs/present-slides/).

Um pôster é A0, a menos que você defina `papersize` como `a1`, `a2`, `a3` ou `a4`. Outros tamanhos, como `letter` ou `a5`, são ignorados. Adicione `orientation: landscape` para um pôster largo.

Uma carta pega o endereço do destinatário em `to` e o seu em `from`. `opening` é a saudação, e `closing` é a linha antes do seu nome, que vem de `author`. `subject` vira a linha de assunto, ou `title`, se não houver `subject`. Escreva um endereço como uma lista, com uma linha por item.

```markdown title="main.md"
---
type: letter
author: "Alex Chen"
from:
  - "Department of Physics"
  - "1 University Road"
to:
  - "Dr. Sam Lee"
  - "Editorial Office"
subject: "Revised manuscript"
opening: "Dear Dr. Lee,"
closing: "Yours sincerely,"
---

Thank you for the reviewers' comments. The revised manuscript answers each one.
```

**Tipo de documento**, em [Configurações do documento](/docs/document-settings/#markdown), escreve a linha `type` para você. Uma [exportação para LaTeX](/docs/export/#what-each-format-keeps) também segue o tipo, e uma [exportação para PowerPoint](/docs/export/#presentation-and-book-exports) de slides usa o mesmo `slide-level`. O [`oleafly build`](/docs/cli/#build-a-project) compila todos os tipos do mesmo jeito que o aplicativo.

## Edição em Código e Visual

O alternador no início da barra de ferramentas tem três modos. **Código** edita o Markdown diretamente. **Visual** oferece edição formatada para títulos, parágrafos, listas, links, imagens e tabelas. **Ambos** mostra o código-fonte e o texto formatado juntos. Abra o menu dele para escolher **Empilhado** ou **Dividir**. Projetos novos abrem em Código, e cada projeto lembra o modo em que você o deixou.

Sublinhado, realce, sobrescrito e subscrito são controles de formatação do Pandoc no modo Código. Os botões deles ficam ocultos no modo Visual. Use Código ao trabalhar com metadados, sintaxe de citação ou outras construções do código-fonte.

[Baixe o código-fonte do exemplo](/examples/writing-example.md)

## Todas as ferramentas da barra

Selecione um texto antes de clicar em um controle de formatação. No modo Código, a maioria das ferramentas envolve a seleção ou insere um espaço reservado. Abra **Mais opções de formatação** (`…`) para acessar controles que não cabem na barra.

### Código / Visual

Alterne entre **Código**, **Visual** e **Ambos**. O documento continua sendo código-fonte Markdown em todos os modos.

### Desfazer

Reverte a última edição. ⌘Z / Ctrl+Z.

### Refazer

Restaura uma edição desfeita. **⌘Shift+Z / Ctrl+Shift+Z**.

### Título → Título

Escolha **Título** no menu de título para inserir `# Title`. Substitua o texto do título pelo seu próprio título.

### Título → Seção

Escolha **Seção** no menu de título para inserir `## Section`. Substitua o texto do título pelo seu próprio título.

### Título → Subseção

Escolha **Subseção** no menu de título para inserir `### Subsection`. Substitua o texto do título pelo seu próprio título.

### Título → Subsubseção

Escolha **Subsubseção** no menu de título para inserir `#### Subsubsection`. Substitua o texto do título pelo seu próprio título.

### Título → Título menor

Escolha **Título menor** no menu de título para inserir `##### Minor heading`. Substitua o texto do título pelo seu próprio título.

### Título → Título de parágrafo

Escolha **Título de parágrafo** no menu de título para inserir `###### Paragraph heading`. Substitua o texto do título pelo seu próprio título.

### Lista com marcadores

Inicia uma lista não ordenada. `- Item`.

### Lista numerada

Inicia uma sequência. `1. Item`.

### Lista de tarefas

No modo Código, adicione uma tarefa e mude `[ ]` para `[x]` ao concluí-la. `- [ ] Task`.

### Citação em bloco

Coloca uma citação em uma linha própria. `> quoted text`.

### Negrito

Dá ênfase ao texto selecionado. `**text**`; ⌘B / Ctrl+B.

### Itálico

Dá ênfase a um termo. `*text*`; ⌘I / Ctrl+I.

### Tachado

Marca o texto como substituído. `~~text~~`.

### Código em linha

Formata um nome de arquivo, comando ou identificador. Texto entre crases.

### Sublinhado

Selecione uma frase no modo Código. `[text]{.underline}`.

### Realce

Selecione uma frase no modo Código. `[text]{.mark}`.

### Sobrescrito

Selecione o expoente no modo Código. `^text^`.

### Subscrito

Selecione o subscrito no modo Código. `~text~`.

Sublinhado e realce usam atributos do Pandoc para que a formatação chegue ao PDF. Use esses controles em vez de adicionar tags HTML brutas ao manuscrito.

### Inserir link

No modo **Código**: insere `[link text](url)`. Substitua os dois espaços reservados.

No modo **Visual**: abre **URL do link**. Digite o endereço e aplique-o à sua seleção. Use **Remover link** para manter o texto sem o link.

### Inserir imagem

No modo **Código**: insere `![caption](image-filename)`. Substitua o caminho e a legenda.

No modo **Visual**: abre **Arquivo de imagem**. Digite um caminho do projeto, como `figures/plot.png`, e aplique-o.

Imagens PNG, JPG, PDF, SVG, GIF, WebP e BMP entram todas no PDF. O Oleafly converte SVG, GIF e WebP para você quando compila. Imagens TIFF, AVIF, HEIC e JPEG XL não entram: a compilação para e nomeia o arquivo, então salve-o em um dos outros formatos e compile de novo. Se uma conversão falhar, confira se a imagem abre, ou salve-a como PNG ou PDF.

### Inserir tabela

No modo **Código**: insere três colunas, um cabeçalho e duas linhas de dados. Substitua os nomes das colunas e as células.

No modo **Visual**: insere uma tabela editável com as mesmas dimensões iniciais.

### Desenhar um diagrama

Abre o [compositor de diagramas](/docs/figures-diagrams/) no modo Mermaid. Desenhe um fluxograma na tela ou edite o código Mermaid e escolha **Inserir como Mermaid** para adicioná-lo no cursor como um bloco de código `mermaid` cercado. Veja [Diagramas Mermaid](#mermaid-diagrams).

### Análise do documento

Lista os títulos, as figuras, as tabelas, as equações, as etiquetas, as citações e as pendências do documento na ordem do código-fonte, cada um vinculado à sua linha. Ele também lê o título, os autores, as palavras-chave, a data e o resumo do front matter e pode copiá-los para um formulário de submissão. Veja [Análise do documento](/docs/document-insights/).

### Configurações do documento

Muda a classe do documento, o tamanho da página, as colunas, as margens, a fonte do corpo, o tamanho da fonte, o idioma, o espaçamento entre linhas e a numeração das seções. O Oleafly escreve as suas escolhas no front matter YAML que o Pandoc lê e adiciona um bloco de front matter se o arquivo não tiver nenhum. Veja [Configurações do documento](/docs/document-settings/#markdown).

### Informações do projeto

No modo **Código**: mostra estatísticas do projeto e informações da seleção.

No modo **Visual**: mostra estatísticas da superfície de edição visual.

### Localizar

No modo **Código**: abre a busca do arquivo ativo com ⌘F / Ctrl+F.

No modo **Visual**: o botão Localizar da barra do código-fonte fica oculto.

Importe a imagem pela árvore de arquivos antes de referenciá-la. Mantenha os caminhos das imagens relativos ao manuscrito, para que o pacote de código-fonte funcione em outro computador.

![Um caderno de laboratório em Markdown editado nas visualizações de código-fonte e visual, com a tabela e a lista de tarefas sempre em sincronia.](https://cdn.oleafly.com/images/gifs/desktop/markdown-notebook.gif?v=2)

## Equações e blocos de código

Escreva matemática em linha como `$x^2$`. Coloque uma equação em bloco entre dois pares de cifrões:

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

Para um exemplo de código, envolva o código em três crases e coloque a linguagem dele depois da cerca de abertura. Essas são construções do código-fonte; a barra de ferramentas do Markdown não tem um botão separado de equação ou de bloco de código cercado.

No modo Visual, um bloco cercado continua sendo um bloco de código e mantém a linguagem e as linhas em branco, então os diagramas Mermaid sobrevivem. Digite três crases para começar um bloco novo e pressione Tab para recuar dentro de um.

## Diagramas Mermaid

Escolha **Desenhar um diagrama** na barra de ferramentas para fazer um fluxograma Mermaid no compositor de diagramas. **Inserir como Mermaid** o adiciona como um bloco de código cercado:

````markdown
```mermaid
flowchart LR
  A[Sample] --> B[Measure]
```
````

No modo **Ambos**, o lado formatado desenha o bloco como um diagrama. Um PDF precisa de uma imagem, então o compositor também salva um PNG renderizado em `figures/mermaid-<hash>.png`, e a compilação coloca essa imagem no lugar do bloco. O diagrama, portanto, também aparece no PDF compilado e nas exportações para Word, HTML, EPUB e PowerPoint. Se você editar o bloco à mão depois, o PDF mostra o código até você inserir ou salvar o diagrama pelo compositor de novo. Veja [Mermaid em documentos Markdown](/docs/figures-diagrams/#mermaid-in-markdown-documents).

## Texto em outros idiomas

O Oleafly escolhe fontes para as escritas que encontra no documento, então coreano, japonês, chinês, árabe, hebraico, grego, cirílico, devanágari, tailandês e várias outras escritas aparecem sem nenhuma configuração. Símbolos e emoji também recebem uma fonte, com o emoji em preto e branco. Um documento escrito quase todo em árabe ou hebraico corre da direita para a esquerda.

Os caracteres chineses aparecem tanto em texto chinês quanto em japonês, então defina `lang` no front matter para obter a fonte certa: `ja` para japonês, `zh` para chinês simplificado, `zh-TW` para chinês tradicional ou `ko` para coreano. Sem `lang`, o Oleafly vai pelo texto: kana significa japonês e hangul significa coreano.

```markdown title="main.md"
---
title: "実験ノート"
lang: ja
---
```

As fontes que você mesmo escolhe vêm primeiro. Quando o front matter define `mainfont` ou `CJKmainfont`, ou o `header-includes` configura fontes, o Oleafly deixa essa parte em paz.

### Caracteres ausentes no PDF

Quando nenhuma fonte em uso tem um caractere, o PDF ainda assim é gerado sem ele, e a compilação mostra um aviso com uma amostra dos caracteres ausentes. Para corrigir:

- Para texto em coreano, chinês ou japonês, defina `CJKmainfont` no front matter com uma fonte instalada no seu computador que tenha os caracteres.
- Para outro texto, defina `mainfont` do mesmo jeito. A **Fonte do texto**, nas [Configurações do documento](/docs/document-settings/#markdown), a escreve para você.
- Para um símbolo raro, use uma imagem.

## Citações e bibliografia

Importe ou crie `references.bib`, adicione `bibliography: references.bib` aos metadados YAML e cite uma chave existente com `[@citation-key]`. O Pandoc usa a bibliografia para produzir citações formatadas e uma lista de referências.

Se o front matter não nomeia nenhuma bibliografia, ou nomeia um arquivo que não existe, a compilação usa os arquivos `.bib` do projeto que contêm as chaves que você cita. Uma citação sem nenhuma bibliografia permanece no PDF como você a digitou, como `[@smith2020]`, para você poder escrever primeiro e acrescentar as referências depois. Um documento que não cita nada compila sem ler nenhum arquivo `.bib`.

[Encontre e gerencie referências →](/docs/citations/)

## Importar e exportar

Para manter um rascunho existente em Markdown, crie um Documento Markdown em branco, cole o rascunho em `main.md` e importe as imagens e a bibliografia dele. A importação separada de **Documento Markdown** da biblioteca atualmente converte um rascunho em LaTeX. [Rotas de importação](/docs/import-project/) explica os dois caminhos.

Compile para PDF ou use **Exportar** para criar Word, HTML, Typst, LaTeX, PowerPoint, EPUB ou texto simples. As exportações para LaTeX e Typst mantêm a bibliografia e apontam para os seus arquivos de imagem em vez de copiá-los, então mantenha esses arquivos junto da exportação. Quando o Pandoc deixa algo de fora, a exportação é salva com avisos, e **Mostrar avisos** lista o que foi descartado. Use um ZIP do código-fonte para compartilhar o Markdown original e os recursos dele. [Exportar o seu trabalho](/docs/export/) cobre a sequência e as verificações a fazer no arquivo convertido.
