Se você já tentou criar um PDF com aparência profissional — relatório, ofício, ata, apresentação acadêmica — sabe a dor de cabeça que isso pode ser. O LaTeX resolve, mas exige uma curva de aprendizado longa e uma sintaxe que parece arqueologia. O Word, Writer e similares resolve parcialmente, mas perde o controle tipográfico quando o documento cresce.

O Typst é a alternativa moderna para os dois. É uma linguagem de marcação compilada — você escreve em arquivos .typ, roda um comando, e obtém um PDF com qualidade tipográfica impecável. A sintaxe é limpa, a compilação é instantânea, e o resultado é consistente toda vez.

Este guia reúne os principais comandos, organizados por categoria, com exemplos prontos para usar.

Instalação rápida

# Via Cargo (requer Rust)
cargo install typst-cli

# Compilar um arquivo
typst compile documento.typ

# Modo de observação (recompila ao salvar)
typst watch documento.typ

Há também um editor online em typst.app — útil para experimentar sem instalar nada.

Editores para Linux

O fluxo mais simples é usar qualquer editor de texto com o comando typst watch rodando no terminal. Mas se você prefere uma experiência integrada com preview ao lado do código, há duas opções nativas para Linux que valem a pena conhecer.

Katvan

O Katvan é um editor dedicado ao Typst, leve e de código aberto (licença GPL-3), escrito em C++ com Qt. A versão mais recente é a 0.12.0 (dezembro de 2025) e já inclui o compilador Typst embutido — não é necessário instalar o CLI separadamente.

Recursos principais:

• Preview ao vivo com busca direta e inversa (clique no PDF para ir ao trecho do código e vice-versa)
• Destaque de sintaxe e indentação automática
• Correção ortográfica via dicionários Hunspell
• Autocompletar
• Painel de etiquetas (labels) para navegação rápida por referências
• Seletor de símbolos e seletor de cores com geração automática da expressão Typst
• Contagem de palavras na barra de status

Instalação no Linux:

# AppImage (recomendado — funciona na maioria das distribuições)
# Baixe em: https://github.com/IgKh/katvan/releases
chmod +x katvan-*.AppImage
./katvan-*.AppImage

# Flatpak (via Flathub)
flatpak install flathub app.katvan.Katvan

# Arch Linux (via AUR)
yay -S katvan

# Corretor ortográfico em português (após instalar o Katvan)
sudo apt install hunspell-pt-br   # Debian/Ubuntu
sudo dnf install hunspell-pt      # Fedora

Nota: o Katvan nasceu com foco em escrita em idiomas da direita para a esquerda (árabe, hebraico), o que explica alguns recursos específicos de bidirecionalidade. Para escrita em português, esses recursos simplesmente ficam em segundo plano e o editor funciona normalmente.

Typesetter

O Typesetter é um editor minimalista para Typst, construído com Rust e GTK, seguindo as diretrizes de interface do GNOME. Está disponível no Flathub desde novembro de 2025.

Recursos principais:

• Interface adaptativa e sem distrações, focada na escrita
• Preview automático que atualiza enquanto você digita
• Clique no preview para ir ao trecho correspondente no código
• Lupa para inspecionar detalhes do PDF
• Verificação de acessibilidade: simula diferentes tipos de daltonismo
• Scrolling centralizado, que mantém o cursor visualmente ancorado
• Suporte a pacotes do ecossistema Typst (pode buscar online quando necessário)
• Totalmente local — nenhum arquivo sai da sua máquina

Instalação no Linux:

# Flatpak (via Flathub) — método recomendado
flatpak install flathub net.trowell.typesetter

Comparação rápida

Ambos são gratuitos, de código aberto e funcionam completamente offline. A escolha depende do estilo de trabalho: o Katvan oferece mais recursos para quem escreve documentos técnicos complexos; o Typesetter prioriza uma experiência limpa e sem distrações. Pra quem usa VSCODE, há extensões para trabalhar com Typst.

1. Configuração de página

Toda a configuração global do documento fica no #set page(), normalmente no início do arquivo.

#set page(
  paper: "a4",
  margin: (top: 4cm, bottom: 2cm, left: 2cm, right: 2cm),
)

O parâmetro paper aceita os valores mais comuns: "a4", "a3", "us-letter", "us-legal". As margens podem ser definidas individualmente ou com um único valor para todos os lados.

// Margem igual em todos os lados
#set page(margin: 2.5cm)

// Orientação paisagem
#set page(paper: "a4", flipped: true)

2. Formatação de texto

O #set text() define as propriedades tipográficas globais. Fonte, tamanho, idioma e região controlam tanto a aparência quanto a hifenização automática.

#set text(
  font: "New Computer Modern",
  size: 12pt,
  lang: "pt",
  region: "br",
)

Ênfase inline

Para negrito, itálico ou código em trechos específicos, use a sintaxe de marcação ou as funções equivalentes:

// Sintaxe de marcação
*negrito*   _itálico_   `código inline`

// Funções equivalentes
#strong[negrito]
#emph[itálico]

// Controle fino de peso, tamanho e cor
#text(weight: "bold", size: 11pt)[Texto especial]
#text(fill: red)[Texto vermelho]
#text(fill: luma(150))[Tom de cinza]

3. Parágrafos e espaçamento

O #set par() controla o espaçamento interno entre linhas e o espaço entre parágrafos.

#set par(
  justify: true,    // texto justificado
  leading: 0.8em,   // espaço entre linhas
  spacing: 1.2em,   // espaço entre parágrafos
)

O espaçamento manual é feito com #v() (vertical) e #h() (horizontal):

#v(2cm)               // espaço vertical fixo
#v(1fr)               // preenche o espaço restante da página
#v(0.5cm, weak: true) // espaço "fraco" (colapsa com outros espaços adjacentes)

#h(1fr)               // empurra o conteúdo seguinte para a direita
#h(3cm)               // recuo horizontal fixo

4. Títulos e numeração

Títulos são criados com = (nível 1), == (nível 2) e === (nível 3). O #set heading() ativa a numeração automática.

#set heading(numbering: "1.1")

= Capítulo Principal
== Seção
=== Subseção

Padrões de numeração disponíveis:

5. Sumário automático

O Typst gera sumários automaticamente a partir dos títulos do documento.

#outline(
  title: "Sumário",
  indent: auto,
  depth: 3,       // até o 3º nível de título
)

// Para lista de figuras
#outline(
  title: "Lista de Figuras",
  target: figure.where(kind: image),
)

6. Cabeçalho e rodapé

Cabeçalho e rodapé são definidos dentro do #set page(), nos parâmetros header e footer. Eles aceitam qualquer conteúdo Typst.

#set page(
  header: [
    #grid(
      columns: (auto, 1fr),
      align: horizon,
      column-gutter: 0.8cm,
      image("logo.svg", width: 3cm),
      align(center)[Nome da Instituição],
    )
    #line(length: 100%, stroke: 1pt + gray)
  ],

  footer: context {
    [
      #line(length: 100%, stroke: 1pt + gray)
      #datetime.today().display("[day]/[month]/[year]")
      #h(1fr)
      Página #counter(page).display()
      de #context counter(page).final().first()
    ]
  },
)

Para suprimir cabeçalho ou rodapé em páginas específicas (como a capa):

#page(header: none, footer: none)[
  Conteúdo da capa aqui
]

7. Listas

Listas não numeradas usam - e numeradas usam +.

// Lista com marcadores
- Primeiro item
- Segundo item
  - Subitem (dois espaços de recuo)

// Lista numerada
+ Passo um
+ Passo dois
+ Passo três

// Com marcador personalizado
#list(
  marker: [→],
  [Item A],
  [Item B],
)

8. Tabelas

Tabelas são criadas com #table(). O parâmetro columns define quantidade e largura das colunas. O parâmetro fill com uma função permite colorir linhas alternadas ou o cabeçalho.

#table(
  columns: (auto, 1fr, 1fr, auto),

  // Colorir linha 0 (cabeçalho) com cinza
  fill: (_, row) => if row == 0 { luma(220) },

  // Alinhamento por coluna
  align: (center, left, left, center),

  // Cabeçalho
  [*#*], [*Nome*], [*Cargo*], [*Data*],

  // Dados
  [1], [Ana Souza],  [Analista], [02/02/2026],
  [2], [João Lima],  [Diretor],  [03/02/2026],
)

Dica: use 1fr para colunas que devem preencher o espaço disponível, e auto para colunas que devem se ajustar ao conteúdo.

9. Imagens

// Imagem simples com largura definida
#image("logo.svg", width: 3cm)

// Imagem centralizada com legenda numerada
#figure(
  image("grafico.png", width: 80%),
  caption: [Evolução dos dados em 2025],
)

// Alinhamento manual
#align(center)[
  #image("foto.jpg", width: 60%)
]

10. Contadores e numeração de páginas

O Typst mantém contadores internos para páginas, figuras, títulos e outros elementos.

// Exibir número da página atual
#counter(page).display()

// Total de páginas (requer context)
#context counter(page).final().first()

// Reiniciar numeração (ex.: após a capa)
#counter(page).update(1)

// Exibir no formato "3 / 12"
#counter(page).display("1 / 1", both: true)

// Contador personalizado
#let meu-contador = counter("itens")
#meu-contador.step()
#meu-contador.display()

11. Variáveis e funções

O Typst é uma linguagem de programação completa. Você pode definir variáveis, arrays e funções para evitar repetição.

// Variável simples
#let titulo = "Relatório Final"
#let ano = 2025

// Array e acesso por índice (começa em 0)
#let meses = ("janeiro", "fevereiro", "março" /* ... */)
#meses.at(0)   // → "janeiro"

// Data dinâmica
#let hoje = datetime.today()
#hoje.day()    // número do dia
#hoje.month()  // número do mês
#hoje.year()   // ano
#hoje.display("[day]/[month]/[year]")

// Função reutilizável
#let destaque(corpo) = text(fill: red, weight: "bold")[#corpo]
#destaque[Atenção: prazo encerrado]

12. Layout: Grid e Align

// Grid divide o espaço em colunas
#grid(
  columns: (1fr, 1fr),       // duas colunas iguais
  column-gutter: 1cm,
  [Coluna esquerda],
  [Coluna direita],
)

// Alinhamento
#align(center)[Centralizado]
#align(right)[À direita]
#align(center + horizon)[Centro absoluto]

13. Linhas, caixas e quebras

// Linha horizontal
#line(length: 100%)
#line(length: 100%, stroke: 1pt + gray)

// Quebra de página
#pagebreak()
#pagebreak(weak: true)  // só quebra se necessário

// Múltiplas colunas
#columns(2)[
  Texto em duas colunas...
]

// Box (inline) e Block (bloco)
#box(width: 100%)[Conteúdo inline]

#block(
  fill: luma(240),
  inset: 1em,
  radius: 4pt,
)[Caixa cinza com bordas arredondadas]

// Retângulo decorativo
#rect(width: 100%, height: 2pt, fill: black)

14. Referências cruzadas, links e notas

// Definir rótulo em um título
= Introdução <intro>

// Referenciar em outro ponto
Veja a @intro para mais detalhes.

// Link externo
#link("https://typst.app")[Site oficial do Typst]

// Nota de rodapé
Texto com nota#footnote[Conteúdo da nota de rodapé.]

15. Matemática

// Inline: entre cifrões simples
O resultado é $x = (-b ± sqrt(b^2 - 4a c)) / (2a)$.

// Bloco: cifrão duplo em linha separada
$ sum_(i=1)^n i = (n(n+1)) / 2 $

16. Condicionais e laços

// Condicional
#if rascunho {
  text(fill: red)[RASCUNHO]
} else {
  [VERSÃO FINAL]
}

// Laço com array
#let itens = ("Alpha", "Beta", "Gamma")
#for item in itens [
  - #item
]

Referência rápida

A documentação oficial completa, com referência de todas as funções e um editor online, está em typst.app/docs.