# Escolha um motor de documento

Entenda como documentos LaTeX, Typst, Markdown, Quarto e Calepin se tornam um PDF e escolha o compilador de que o seu projeto precisa.

Um motor transforma o seu código-fonte no documento que as pessoas leem. Escolha a linguagem do documento ao criar um projeto. Para um projeto LaTeX, você também pode escolher qual compilador LaTeX executa o build.

## Escolha uma linguagem

| O seu trabalho | Comece com | Como se torna um PDF |
|---|---|---|
| Um artigo para periódico, uma classe de tese consagrada ou um projeto `.tex` existente | LaTeX | Tectonic, ou um compilador executado por meio de `latexmk` |
| Um artigo, relatório ou currículo novo com sintaxe de diagramação concisa | Typst | O Typst 0.15.1 embutido, ou outra versão do Typst que o projeto fixar |
| Um rascunho de prosa, anotações ou um documento que você quer exportar para vários formatos | Markdown | O Pandoc converte o código-fonte para LaTeX; o Tectonic produz o PDF |
| Um relatório de análise, um artigo ou uma apresentação de slides cujo código R, Python ou Julia produz os resultados | Quarto | O Quarto renderiza arquivos `.qmd` ou `.Rmd` em um PDF, uma página web ou slides |
| Um documento Typst com blocos de código | Calepin | O Calepin executa o código, depois o Typst embutido gera o PDF |

A escolha determina a barra de ferramentas do editor, a sintaxe do código-fonte e os formatos de exportação disponíveis. Trocar de compilador LaTeX não traduz o documento para Typst ou Markdown. Para mover um projeto LaTeX para Typst, [converta-o em um novo projeto Typst](/docs/typst/#convert-a-latex-project-to-typst).

## Tectonic

Use o **Tectonic** para uma configuração LaTeX simples. Ele vem com o Oleafly, baixa os pacotes TeX de que um build precisa e os guarda em cache para builds posteriores. Comece por aqui quando o seu modelo não exigir um compilador específico.

Compile uma vez conectado antes de viajar. Um projeto com cache compila offline; um pacote novo ainda pode precisar de download. Ative **Configurações → Geral → Modo offline** para que o Tectonic use o cache dele.

## pdfLaTeX

Escolha o **pdfLaTeX** quando uma editora ou um projeto existente o especificar. Ele segue o fluxo de trabalho tradicional de LaTeX e combina bem com classes e combinações de pacotes mais antigas. Ele precisa de uma distribuição TeX com o `latexmk` instalado.

## XeLaTeX

Escolha o **XeLaTeX** para um projeto que o solicite, em particular um que use `fontspec`, fontes OpenType ou texto multilíngue. Garanta que as fontes nomeadas no código-fonte estejam instaladas ou incluídas com o projeto. Ele também executa por meio do `latexmk`.

## LuaLaTeX

Escolha o **LuaLaTeX** para um modelo que o exija, para diagramação baseada em Lua ou para o fluxo de trabalho de PDF marcado do Oleafly. PDFs marcados carregam a estrutura do documento, que tecnologias assistivas podem usar. Execute as [verificações de pré-verificação](/docs/preflight/) para inspecionar o resultado; a escolha do compilador sozinha não estabelece a qualidade das marcações.

## Typst

O Oleafly vem com o Typst 0.15.1. Crie um projeto Typst, escreva em arquivos `.typ` e clique em **Compilar de novo**. Não há instalação de TeX para configurar.

A seção **Configurações → Motores → Typst** também pode instalar o Typst 0.11 a 0.15 e usar um Typst já instalado no seu computador. Cada projeto fixa a própria versão, então um artigo mantém o layout quando o Oleafly passa para um Typst mais novo. O Typst baixa pacotes do Typst Universe na primeira vez que um documento os importa, e o **Modo offline** o limita a pacotes já em cache ou mantidos no projeto.

O Typst tem sintaxe, pacotes e tratamento de fontes próprios. [Projetos Typst](/docs/typst/) cobre versões, pacotes, fontes e variantes de build. O [guia de escrita em Typst](/docs/writing/typst/) tem um documento inicial completo e os controles da barra de ferramentas.

## Markdown

O Markdown usa o **Pandoc** para preparar um documento diagramado e o Tectonic para construir o PDF. Abra **Configurações → Motores → Markdown** para instalar o Pandoc quando ele estiver ausente. Depois abra o seu projeto Markdown e compile.

Use [Escrita em Markdown](/docs/writing/markdown/) para títulos, listas, matemática e o editor visual. O [guia de exportação](/docs/export/) explica quais formatos de saída o projeto oferece.

## Quarto

O Quarto transforma documentos `.qmd` e `.Rmd` em um PDF, uma página web ou slides. O Oleafly usa o Quarto do seu computador quando encontra um. Se não houver, abra **Configurações → Motores → Quarto** e selecione **Baixar o Quarto 1.10.19**. O botão também mostra o tamanho do download. O Oleafly verifica o download antes de descompactá-lo e guarda a cópia na própria pasta do aplicativo. Se você compilar antes de o Quarto estar lá, a visualização oferece instalá-lo na hora, ou **Abrir as configurações do motor**.

O primeiro formato que o documento declara decide o que você recebe:

- `pdf`, `typst` e `beamer` geram um PDF. `format: typst` não precisa de instalação TeX. `pdf` e `beamer` passam pelo LaTeX, então instale o TinyTeX em **Configurações → Motores → LaTeX** se você ainda não tem TeX.
- `html`, `revealjs` e `dashboard` geram uma página web. Selecione **Abrir no navegador** na visualização para vê-la.

Quando o documento não declara nenhum formato, o Oleafly procura um em `_quarto.yml` ou `_metadata.yml`, na pasta do documento e nas pastas acima dela até a raiz do projeto. Se não houver formato em lugar nenhum, o Quarto gera uma página web. Um arquivo `.Rmd` que indica um `output:` do R Markdown, como `pdf_document`, recebe o formato correspondente do Quarto.

O código roda no R, no Python ou no Julia que já estão no seu computador. O Oleafly nunca os instala, e **Linguagens**, na mesma aba de configurações, mostra os que ele encontrou. O código Python também precisa do Jupyter nesse Python. A exportação oferece DOCX e HTML, ambos renderizados pelo Quarto. O diálogo **Novo projeto** tem dois modelos Quarto: **Quarto article**, um PDF gerado pelo Typst, e **Quarto slides**, uma apresentação reveal.js.

## Calepin

O Calepin executa o código de um documento Typst e coloca os resultados no PDF. Um documento Calepin é um arquivo `.typ` que importa `/.calepin/calepin.typ`. Comece um pelo modelo **Calepin report**, ou abra a seta ao lado de **Compilar de novo** em um projeto Typst e escolha **Calepin** em **Motor (deste projeto)**.

Instale-o em **Configurações → Motores → Calepin** do mesmo jeito que o Quarto, com **Baixar o Calepin 0.0.61**. O Calepin compila com o Typst que vem com o Oleafly. Um bloco cuja linguagem não está instalada mostra uma nota curta, e o resto do documento é gerado mesmo assim. A exportação oferece HTML, renderizado pelo Calepin.

## Permitir código em um projeto

O código de um documento Quarto ou Calepin roda com as suas permissões, então ele fica desligado em cada projeto até você permiti-lo. Depois de uma compilação que precisava de código, um aviso acima do editor diz que o código está desligado e oferece **Permitir código neste projeto**. Você também pode abrir a seta ao lado de **Compilar de novo** e escolher **Executar código neste computador** em **Código (deste computador)**. **Desligado** o desliga de novo. Só permita código se você confiar em todos os arquivos do projeto.

A escolha vale só para este computador. Ela não é salva no projeto, e mudar o motor do projeto desliga o código de novo. Em um [projeto compartilhado](/docs/collaboration/), o Oleafly pergunta mais uma vez, porque qualquer pessoa que pode editar o projeto pode mudar o código dele.

Enquanto o código está desligado:

- O Quarto mostra o código de cada bloco sem executá-lo. Filtros, shortcodes, `_extensions`, scripts de pré-renderização e de pós-renderização e código R inline executam código mesmo assim, então um documento que os usa não compila até você permitir código.
- O Calepin não consegue pular o código. O Oleafly gera o PDF com o Typst puro, a partir dos resultados que o Calepin guardou na última vez que rodou. Se não houver nenhum, a compilação para e pede que você permita código.

Você também precisa confiar em uma pasta que [abre no próprio lugar](/docs/library/#folders-opened-in-place) antes que o Quarto ou o Calepin possam compilá-la. A sincronização entre código-fonte e PDF não está disponível em nenhum dos dois motores.

## Definir um padrão para projetos novos

Abra **Configurações → Motores → LaTeX** e escolha o **Motor de compilação padrão**: **Tectonic (embutido)** ou **latexmk (TeX do sistema)**. Todo projeto LaTeX que você criar depois disso começa nele:

- Um projeto em branco ou um modelo do diálogo **Novo projeto**, e um projeto de pesquisa.
- Um ZIP, uma pasta, um artigo do arXiv ou um repositório do GitHub importado.
- Um documento que você converte em um projeto LaTeX, como um arquivo do Word ou um PDF.

O motor é gravado no `project.json` do projeto, então um coautor que abrir o projeto o compila da mesma forma. Um projeto importado que indica pdfLaTeX, XeLaTeX ou LuaLaTeX mantém esse compilador quando passa para o `latexmk`. O compilador salvo de um projeto existente continua sendo escolha dele.

Uma pasta que você [abre no próprio lugar](/docs/library/#folders-opened-in-place), sem um motor próprio, passa a seguir o padrão assim que você confia nela. Até lá, ela aparece e compila no Tectonic. O Oleafly não grava nada na pasta, em nenhum dos casos.

Para o Typst, abra **Configurações → Motores → Typst** e escolha a versão padrão. Projetos Typst novos fixam a versão que é o padrão quando você os cria. Mudar o padrão depois não move projetos existentes.

## Mudar o compilador do projeto atual

Abra a seta ao lado de **Compilar de novo** na [barra de ferramentas do projeto](/docs/project-toolbar/). Em um projeto LaTeX, escolha Tectonic, Automático, pdfLaTeX, XeLaTeX ou LuaLaTeX em **Compilador (deste projeto)** e compile. Leia o log se um modelo precisar de um pacote ou fonte que a instalação selecionada não tenha.

Em um projeto Typst, o mesmo menu tem **Versão do Typst (deste projeto)** no lugar. Escolha uma versão instalada, ou **Padrão** para seguir as Configurações. O grupo **Motor (deste projeto)** desse menu alterna o documento entre **Typst** e **Calepin**.

## Detectar uma distribuição TeX existente

Abra **Configurações → Motores → LaTeX** e revise a cadeia de ferramentas detectada. O Oleafly procura uma configuração de compilador completa, incluindo o `latexmk` e as ferramentas de apoio. Uma instalação parcial do sistema não tem prioridade sobre uma instalação gerenciada funcionando.

## Instalar o TinyTeX gerenciado

Use o controle de instalação nas configurações do motor LaTeX se você precisar de um compilador tradicional e não tiver um. O Oleafly baixa a própria instalação do TinyTeX em `~/.oleafly/tinytex`; acesso de administrador não é necessário. Reserve cerca de 250 MB para o download inicial e espaço adicional para pacotes.

## Gerenciar pacotes

A lista de pacotes nas configurações do motor LaTeX permite filtrar pacotes, inspecionar descrições e adicioná-los ou removê-los. Selos de marcação identificam pacotes que precisam de atenção extra ao produzir um PDF marcado. Esses controles gerenciam a distribuição TeX usada pelo `latexmk`; o Tectonic tem um cache separado.

[Leia o guia de pacotes LaTeX e PDF marcado →](/docs/latex-engines/)