AnisAbdellatif/typst

O que typst faz?

Typst é um sistema de composição tipográfica baseado em marcação com uma linguagem de script embutida. Um único binário compila .typ → PDF (padrão), PNG, SVG, HTML (experimental) ou um pacote de múltiplos arquivos (experimental). Esta skill tem como alvo Typst 0.15.x (verificado na versão 0.15.1); notas indicam comportamentos que diferem em versões mais antigas.

Os dados de treinamento sobre Typst estão frequentemente desatualizados (era 0.11–0.13). Quando estiver em dúvida sobre uma função, parâmetro ou valor padrão, consulte references/api-signatures.md, depois compile um teste (typst eval '<expr>' ou um arquivo de 5 linhas) em vez de adivinhar.

Fluxo de trabalho

1. Esclareça a saída: PDF (padrão), HTML, PNG/SVG, PDF acessível (PDF/UA), PDF arquivístico (PDF/A)? Tamanho da página, idioma, fontes, estilo de citação, template/periódico?
2. Comece por um esqueleto (abaixo) ou por examples/. Para um periódico/tese/currículo/conjunto de slides, pesquise um pacote primeiro: python3 scripts/search-packages.py "ieee paper" (veja references/packages-and-ecosystem.md).
3. Escreva o arquivo: coloque as regras set/show e as importações no topo, o conteúdo abaixo. Divida projetos grandes com #include e #import.
4. Compile e verifique: typst compile main.typ — leia os diagnósticos (eles têm linha:col e dicas). Verifique visualmente via PNG (typst compile main.typ 'p-{p}.png'), ou textualmente via typst compile main.typ - -f html --features html / pdftotext. Detalhes em references/pitfalls-and-debugging.md.
5. Formate (se disponível): typstyle -i file.typ. Apenas quando o diff estiver limitado às suas próprias edições.
6. Informe quais arquivos foram criados/alterados e como reconstruir.

Esqueleto mínimo

#set document(title: "Meu Documento", author: "Nome")
#set page(paper: "a4", margin: 2.5cm, numbering: "1")
#set text(font: "New Computer Modern", size: 11pt, lang: "pt")
#set par(justify: true, leading: 0.65em)
#set heading(numbering: "1.1")

#title()

= Introdução <intro>
Typst suporta *negrito*, _itálico_, `crua`, matemática $E = m c^2$ e referências como @intro.

== Uma subseção
#lorem(30)

$ integral_0^1 x^2 dif x = 1/3 $

Padrões sempre seguros: #set text(lang: "...") (hifenização, aspas, complementos, acessibilidade), #set document(title: ...) + #title() para o título visível, #set par(justify: true) para o corpo do texto.

Sintaxe em 60 segundos

Modo	Entrar com	Exemplo
Marcação (padrão)	—	= Título, *negrito*, _itálico_, - item, + numerado, / Termo: desc, @rótulo, <rótulo>
Código	# (uma expressão) ou bloco #{ ... }	#let x = 3, #f(1)[corpo], #if a [sim] else [não], #for i in range(3) [#i ]
Matemática	$...$ ($ x $ com espaços = exibição)	$a^2 + b_i$, $sum_(i=1)^n i$, $ vec(1, 2) $
Bloco de conteúdo	[...] dentro de código	#box[oi], let c = [*x*]

• Dentro do código, não repita #: #figure(image("a.png"), caption: [Oi]). Dentro de blocos de conteúdo [...] você volta à marcação: [Total: #x].
• Arrays (1, 2), dicionários (a: 1, b: 2), vazio () / (:), um elemento (1,). Não existem tuplas. Indexe com .at(i), não [i].
• Argumentos nomeados usam : (f(width: 2cm)); = é atribuição apenas dentro de let/código.
• Strings "...", conteúdo [...], cru `...`. Converta com str(x), [#s], eval(s, mode: "markup").
• Comentários: // linha, /* bloco */. Escape especiais com \ (\#, \$, \@, \*, \_, \<); unicode \u{1F600}.
• Unidades de comprimento: pt mm cm in em, fr (fração), %, ângulos deg rad. auto e none são valores.
• set = argumentos padrão para um elemento daqui em diante; show = reestilizar/substituir elementos. context é necessário para ler estilos/contadores/posições (veja references/introspection.md).
• Caminhos: apenas barras normais (0.15). "/x.typ" é relativo à raiz do projeto (raiz padrão: diretório do arquivo principal; altere com --root), "x.typ" é relativo ao arquivo atual.
• Sintaxe de método em toda parte: "abc".len(), (1,2,3).map(x => x*2), rgb("#f00").lighten(30%).

Onde procurar

Necessidade	Leia
Sintaxe, tipos, operadores, métodos de string/array/dict, módulos, closures, conceitos básicos de context	references/syntax-and-scripting.md
Regras set/show, seletores, configuração de página, texto, parágrafos, blocos, grades, colunas, alinhamento, espaçamento, posicionamento, transformações	references/styling-and-layout.md
Títulos, listas, figuras, tabelas, referências, notas de rodapé, sumários, citações, bibliografia/CSL, numeração, links, metadados	references/document-model.md
Equações, sintaxe matemática, símbolos, matrizes, alinhamento, fontes, numeração	references/math.md
Formas, curvas, imagens, cores, gradientes, padrões, traços, cores especiais	references/visuals.md
Contadores, estado, query, locate, metadata, within, convergência de layout, cabeçalhos corridos, measure/layout	references/introspection.md
CSV/JSON/YAML/TOML/XML/CBOR, read, bytes, sys.inputs, eval, plugins WASM, documentos orientados a dados	references/data-and-io.md
Flags da CLI, fontes, PDF/A/UA, acessibilidade, HTML, bundle, PNG/SVG, typst eval, CI/builds reproduzíveis	references/export-and-cli.md
Apresentações de slides (Touying/Polylux, animações, apostilas, notas do apresentador, pdfpc)	references/slides.md
Templates, typst.toml, publicação de pacotes, seleção de pacotes Universe (cetz, fletcher, touying, codly, ...), ferramentas de editor	references/templates-and-packages.md, references/packages-and-ecosystem.md
Tradução LaTeX → Typst, conversão Markdown/pandoc, atualização da versão 0.11–0.14	references/migration.md
Erros, avisos, testes, verificação visual, performance, pegadinhas comuns	references/pitfalls-and-debugging.md
Parâmetros/padrões exatos de cada elemento (verificado no código-fonte 0.15.1)	references/api-signatures.md
Exemplos prontos para compilar	examples/*.typ

Principais pegadinhas (leia antes de escrever)

1. Regras set/show aplicam-se para frente e apenas dentro de seu escopo; coloque-as antes do conteúdo que devem afetar. Um set dentro de [...]/{...} termina com o bloco.
2. Ler qualquer coisa que dependa de posição/estilo requer context: #context counter(page).get(), #context text.size. Sem ele: "só pode ser usado quando o contexto é conhecido".
3. Variáveis capturadas por closures são cópias somente leitura; acumule via fold, loops em um único bloco de código, state ou counter.
4. # é necessário uma vez; #(a + b) para expressões com operadores em marcação; #f(x).g funciona, mas #f (x) (espaço) não chama.
5. Matemática não é texto: palavras com várias letras são símbolos/variáveis (alpha, sin); escreva texto como "texto" ou upright(...). Letras únicas são variáveis em itálico.
6. Strings não são conteúdo: o corpo de um título é conteúdo; use .body, str() ou auxiliar to-string (veja referência de sintaxe) para obter texto.
7. Fontes: apenas fontes instaladas/embutidas/--font-path funcionam; uma família desconhecida apenas avisa e usa fallback. Liste com typst fonts. Para fontes variáveis, omita "Variable"/"VF" no nome (0.15).
8. Pacotes são importados com versões exatas: #import "@preview/cetz:0.5.3" — consulte a versão mais recente no Typst Universe (scripts/search-packages.py) em vez de confiar na memória. Pacotes podem estar desatualizados em relação a um novo compilador.
9. Remoções do 0.15: path() → curve(), pattern → tiling, pdf.embed → pdf.attach, *.decode(...) → passe bytes para json(...) etc., typst query → typst eval, sem barras invertidas em caminhos.
10. Exportação HTML/pacote são experimentais e precisam de --features html / --features bundle.

Idiomas rápidos

// Template reutilizável: regra show com função
#let conf(title: none, authors: (), body) = {
  set page(margin: 2cm)
  set par(justify: true)
  align(center, text(17pt, weight: "bold", title))
  v(1em)
  body
}
#show: conf.with(title: [Meu Artigo])

// Estilizar um nível de título
#show heading.where(level: 1): set text(navy)
#show heading.where(level: 1): it => block(above: 1.5em, below: 1em, it)

// Referências cruzadas e figuras
#figure(table(columns: 2, [A], [B], [1], [2]), caption: [Dados]) <tab:dados>
Veja @tab:dados.

// Conteúdo orientado a dados
#for (nome, pontuacao) in (("Ana", 3), ("Beto", 5)) [- #nome: #pontuacao]

// Entrada em tempo de execução da CLI: typst compile --input mode=draft main.typ
#let rascunho = sys.inputs.at("mode", default: "final") == "rascunho"

Folha de dicas de compilação

typst compile main.typ                 # → main.pdf
typst compile main.typ saida.pdf --root .
typst compile main.typ 'pagina-{0p}.png' --ppi 144
typst watch main.typ                   # recompilar ao alterar
typst eval 'calc.pow(2, 10)'           # avaliar expressão, saída JSON
typst eval --in main.typ 'query(heading).len()'
typst init @preview/charged-ieee       # novo projeto a partir de template
typst fonts --variants                 # fontes instaladas

Exemplos (todos compilam no 0.15.1)

Arquivo	Mostra
examples/memo.typ	memorando curto, grade de cabeçalho, estilo simples
examples/report.typ	página de título, sumário, cabeçalho corrido, figuras/tabelas/notas de rodapé, regras show
examples/academic-paper.typ (+ refs.bib)	equações, ambientes de teoremas, referências cruzadas, citações
examples/data-report.typ (+ data.csv)	CSV → tabela, colunas calculadas, --input, gráfico de barras com formas simples
examples/template.typ + template-usage.typ	função de template reutilizável + componentes
examples/accessible.typ	PDF/A-2a + PDF/UA-1 (--pdf-standard a-2a,ua-1)
examples/dual-target.typ	uma fonte → PDF e HTML (context target(), html.*)
examples/query-export.typ	metadata + exportação de estrutura typst eval
examples/slides-plain.typ, examples/letter.typ	slides sem pacotes e uma carta formal
examples/packages-demo.typ	cetz, fletcher, lilaq, theorion, codly (versões fixadas e verificadas)

Scripts

• scripts/check-snippets.py FILE.md… — compila todos os blocos ```typ (use ```typ-x para blocos ilustrativos/não compiláveis). Execute em qualquer Markdown que você escrever contendo Typst.
• scripts/search-packages.py "palavras-chave" [--category cv] [--name cetz --versions] — consulta o índice do Typst Universe para nomes/versões atuais de pacotes.