# 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.

![Os motores de LaTeX e Typst que o Oleafly encontrou neste computador, com as respectivas versões.](https://cdn.oleafly.com/images/gifs/desktop/settings-engines.gif?v=2)

## 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. Se este computador não tem nenhuma, o Oleafly oferece instalar o TinyTeX quando você o escolhe. Veja [Quando nenhum TeX está instalado](/docs/latex-engines/#when-no-tex-is-installed).

## 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.

## upLaTeX e pLaTeX

Escolha o **upLaTeX** ou o **pLaTeX** para um documento em japonês, como um baseado em `jsarticle` ou `jlreq`. O **Automático** os escolhe sozinho para essas classes. Os dois precisam do suporte a japonês do TeX Live, e o Oleafly pode instalá-lo no TinyTeX quando uma compilação precisar. Veja [Documentos em japonês](/docs/latex-engines/#japanese-documents-uplatex-and-platex).

## 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, que a visualização mostra. A página não consegue acessar o resto do Oleafly. Para abri-la no seu próprio navegador, escolha **Abrir no navegador**, o ícone de globo, na barra de ferramentas da visualização.

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 mesmo vale para um `pdf-engine` diferente de `pdflatex`, `xelatex`, `lualatex` ou `typst`, como `pdf-engine: tectonic`.
- 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, LuaLaTeX, upLaTeX ou pLaTeX 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, LuaLaTeX, upLaTeX ou pLaTeX em **Compilador (deste projeto)** e compile. Se este computador não tem uma distribuição TeX que funcione, um diálogo oferece **Baixar e usar o TinyTeX** ou **Voltar para o Tectonic**. 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 **Gerenciar as distribuições TeX**. Ela lista todas as distribuições que o Oleafly encontrou, inclusive uma que esteja no `PATH` do seu terminal, e marca como **Em uso** a que o `latexmk` usa para compilar. 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. Escolha **Usar nas compilações** em outra distribuição para passar a usá-la.

O MiKTeX precisa do Perl para rodar o `latexmk`. Sem ele, o MiKTeX mostra **o latexmk precisa do Perl**. Veja [MiKTeX e Perl](/docs/latex-engines/#miktex-and-perl).

## Instalar o TinyTeX gerenciado

Escolha **Baixar o TinyTeX (~250 MB)** 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; acesso de administrador não é necessário. Reserve cerca de 250 MB para o download inicial e até cerca de 1 GB à medida que os modelos acrescentam pacotes. Você pode cancelar o download e retomá-lo depois, e **Atualizar** aparece quando o TinyTeX gerenciado é mais antigo que a versão que o Oleafly espera. No Linux, instale o Perl antes. Veja [Instalar e atualizar o TinyTeX](/docs/latex-engines/#install-and-update-tinytex).

## 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. O TeX Live do Debian, do Ubuntu ou do Fedora é gerenciado com `apt` ou `dnf`, e o MiKTeX com o MiKTeX Console.

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