AnisAbdellatif/typst

¿Qué hace typst?

Typst es un sistema de composición tipográfica basado en marcado con un lenguaje de script integrado. Un solo binario compila .typ → PDF (por defecto), PNG, SVG, HTML (experimental) o un paquete multifichero (experimental). Esta habilidad está dirigida a Typst 0.15.x (verificada contra 0.15.1); las notas marcan comportamientos que difieren en versiones anteriores.

Los datos de entrenamiento sobre Typst suelen estar desactualizados (era 0.11–0.13). Cuando no estés seguro sobre una función, parámetro o valor por defecto, consulta references/api-signatures.md y luego compila una prueba (typst eval '<expr>' o un archivo de 5 líneas) en lugar de adivinar.

Flujo de trabajo

1. Aclara la salida: ¿PDF (por defecto), HTML, PNG/SVG, PDF accesible (PDF/UA), PDF de archivo (PDF/A)? Tamaño de página, idioma, fuentes, estilo de citas, plantilla/revista?
2. Empieza desde un esqueleto (abajo) o desde examples/. Para una revista/tesis/CV/presentación, busca primero un paquete: python3 scripts/search-packages.py "ieee paper" (consulta references/packages-and-ecosystem.md).
3. Escribe el archivo: coloca las reglas set/show y las importaciones al principio, el contenido después. Divide proyectos grandes con #include e #import.
4. Compila y verifica: typst compile main.typ — lee los diagnósticos (tienen línea:col y sugerencias). Verifica visualmente mediante PNG (typst compile main.typ 'p-{p}.png'), o textualmente mediante typst compile main.typ - -f html --features html / pdftotext. Detalles en references/pitfalls-and-debugging.md.
5. Formatea (si está disponible): typstyle -i file.typ. Solo cuando el diff se limite a tus propias ediciones.
6. Informa qué archivos se crearon/modificaron y cómo reconstruirlos.

Esqueleto mínimo

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

#title()

= Introducción <intro>
Typst soporta *negrita*, _cursiva_, `raw`, matemáticas $E = m c^2$ y referencias como @intro.

== Una subsección
#lorem(30)

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

Valores por defecto siempre seguros: #set text(lang: "...") (separación silábica, comillas, suplementos, accesibilidad), #set document(title: ...) + #title() para el título visible, #set par(justify: true) para el texto del cuerpo.

Sintaxis en 60 segundos

Modo	Entrar con	Ejemplo
Marcado (por defecto)	—	= Título, *negrita*, _cursiva_, - elemento, + numerado, / Término: desc, @etiqueta, <etiqueta>
Código	# (una expresión) o bloque #{ ... }	#let x = 3, #f(1)[cuerpo], #if a [sí] else [no], #for i in range(3) [#i ]
Matemáticas	$...$ ($ x $ con espacios = en línea)	$a^2 + b_i$, $sum_(i=1)^n i$, $ vec(1, 2) $
Bloque de contenido	[...] dentro de código	#box[hola], let c = [*x*]

• Dentro del código, no repitas #: #figure(image("a.png"), caption: [Hola]). Dentro de los bloques [...] vuelves al modo marcado: [Total: #x].
• Arrays (1, 2), diccionarios (a: 1, b: 2), vacíos () / (:), de un elemento (1,). No hay tuplas. Indexa con .at(i), no con [i].
• Los argumentos con nombre usan : (f(width: 2cm)); = es asignación solo dentro de let/código.
• Cadenas "...", contenido [...], raw `...`. Convierte con str(x), [#s], eval(s, mode: "markup").
• Comentarios: // línea, /* bloque */. Escapa especiales con \ (\#, \$, \@, \*, \_, \<); unicode \u{1F600}.
• Unidades de longitud: pt mm cm in em, fr (fracción), %, ángulos deg rad. auto y none son valores.
• set = argumentos por defecto para un elemento desde aquí en adelante; show = reestilizar/reemplazar elementos. Se necesita context para leer estilos/contadores/posiciones (consulta references/introspection.md).
• Rutas: solo barras inclinadas hacia adelante (0.15). "/x.typ" es relativo a la raíz del proyecto (raíz por defecto: directorio del archivo principal; cambia con --root), "x.typ" es relativo al archivo actual.
• Sintaxis de método en todas partes: "abc".len(), (1,2,3).map(x => x*2), rgb("#f00").lighten(30%).

Dónde buscar

Necesidad	Leer
Sintaxis, tipos, operadores, métodos de cadena/array/dict, módulos, clausuras, conceptos básicos de context	references/syntax-and-scripting.md
Reglas set/show, selectores, configuración de página, texto, párrafos, bloques, rejillas, columnas, alineación, espaciado, colocación, transformaciones	references/styling-and-layout.md
Títulos, listas, figuras, tablas, referencias, notas al pie, esquemas, citas, bibliografía/CSL, numeración, enlaces, metadatos	references/document-model.md
Ecuaciones, sintaxis matemática, símbolos, matrices, alineación, fuentes, numeración	references/math.md
Formas, curvas, imágenes, colores, degradados, teselados, trazos, colores especiales	references/visuals.md
Contadores, estado, query, locate, metadata, within, convergencia de maquetación, encabezados dinámicos, measure/layout	references/introspection.md
CSV/JSON/YAML/TOML/XML/CBOR, read, bytes, sys.inputs, eval, plugins WASM, documentos basados en datos	references/data-and-io.md
Banderas de CLI, fuentes, PDF/A/UA, accesibilidad, HTML, bundle, PNG/SVG, typst eval, compilaciones CI/reproducibles	references/export-and-cli.md
Presentaciones (Touying/Polylux, animaciones, folletos, notas del orador, pdfpc)	references/slides.md
Plantillas, typst.toml, publicación de paquetes, selecciones de Universe (cetz, fletcher, touying, codly, ...), herramientas de editor	references/templates-and-packages.md, references/packages-and-ecosystem.md
Traducción de LaTeX → Typst, conversión Markdown/pandoc, actualización desde 0.11–0.14	references/migration.md
Errores, advertencias, pruebas, verificación visual, rendimiento, errores comunes	references/pitfalls-and-debugging.md
Parámetros/valores por defecto exactos de cada elemento (verificados contra el código fuente de 0.15.1)	references/api-signatures.md
Iniciadores listos para compilar	examples/*.typ

Principales errores (léelos antes de escribir)

1. Las reglas set/show se aplican hacia adelante y solo dentro de su ámbito; colócalas antes del contenido que deben afectar. Un set dentro de [...]/{...} termina con el bloque.
2. Leer cualquier cosa que dependa de la posición/estilo necesita context: #context counter(page).get(), #context text.size. Sin él: "solo se puede usar cuando se conoce el contexto".
3. Las variables capturadas por clausuras son copias de solo lectura; acumula mediante fold, bucles en un solo bloque de código, state o counter.
4. # se necesita una vez; #(a + b) para expresiones con operadores en marcado; #f(x).g funciona pero #f (x) (espacio) no llama.
5. Las matemáticas no son texto: las palabras de varias letras son símbolos/variables (alpha, sin); escribe texto como "texto" o upright(...). Las letras individuales son variables en cursiva.
6. Las cadenas no son contenido: el cuerpo de un título es contenido; usa .body, str() o el helper to-string (consulta la referencia de sintaxis) para obtener texto.
7. Fuentes: solo funcionan las fuentes instaladas/incrustadas/--font-path; una familia desconocida solo advierte y recurre a otra. Lista con typst fonts. Para fuentes variables omite "Variable"/"VF" en el nombre (0.15).
8. Los paquetes se importan con versiones exactas: #import "@preview/cetz:0.5.3" — busca la última en Typst Universe (scripts/search-packages.py) en lugar de confiar en la memoria. Los paquetes pueden ir por detrás de un nuevo compilador.
9. Eliminaciones en 0.15: path() → curve(), pattern → tiling, pdf.embed → pdf.attach, *.decode(...) → pasa bytes a json(...) etc., typst query → typst eval, sin barras invertidas en rutas.
10. La exportación a HTML/bundle es experimental y necesita --features html / --features bundle.

Modismos rápidos

// Plantilla reutilizable: regla show con función
#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: [Mi Artículo])

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

// Referencias cruzadas y figuras
#figure(table(columns: 2, [A], [B], [1], [2]), caption: [Datos]) <tab:datos>
Ver @tab:datos.

// Contenido basado en datos
#for (nombre, puntuacion) in (("Ana", 3), ("Bo", 5)) [- #nombre: #puntuacion]

// Entrada en tiempo de ejecución desde CLI: typst compile --input mode=borrador main.typ
#let borrador = sys.inputs.at("mode", default: "final") == "borrador"

Chuleta de compilación

typst compile main.typ                 # → main.pdf
typst compile main.typ out.pdf --root .
typst compile main.typ 'page-{0p}.png' --ppi 144
typst watch main.typ                   # recompila al cambiar
typst eval 'calc.pow(2, 10)'           # evalúa una expresión, salida JSON
typst eval --in main.typ 'query(heading).len()'
typst init @preview/charged-ieee       # nuevo proyecto desde una plantilla
typst fonts --variants                 # fuentes instaladas

Ejemplos (todos compilan en 0.15.1)

Archivo	Muestra
examples/memo.typ	memo corto, cuadrícula de encabezado, estilo simple
examples/report.typ	portada, índice, encabezado dinámico, figuras/tablas/notas al pie, reglas show
examples/academic-paper.typ (+ refs.bib)	ecuaciones, entornos de teoremas, referencias cruzadas, citas
examples/data-report.typ (+ data.csv)	CSV → tabla, columnas calculadas, --input, gráfico de barras con formas simples
examples/template.typ + template-usage.typ	función de plantilla reutilizable + componentes
examples/accessible.typ	PDF/A-2a + PDF/UA-1 (--pdf-standard a-2a,ua-1)
examples/dual-target.typ	una fuente → PDF y HTML (context target(), html.*)
examples/query-export.typ	metadata + exportación de estructura typst eval
examples/slides-plain.typ, examples/letter.typ	diapositivas sin paquetes y una carta formal
examples/packages-demo.typ	cetz, fletcher, lilaq, theorion, codly (versiones fijas, verificadas)

Scripts

• scripts/check-snippets.py FILE.md… — compila cada bloque ```typ (usa ```typ-x para bloques ilustrativos/no compilables). Ejecútalo en cualquier Markdown que escribas que contenga Typst.
• scripts/search-packages.py "palabras clave" [--category cv] [--name cetz --versions] — consulta el índice de Typst Universe para obtener nombres/versiones actuales de paquetes.