# Proyectos de Typst

Fija una versión de Typst por proyecto, añade paquetes de Typst Universe, controla las tipografías, las variantes de compilación y los PDF reproducibles, y convierte un proyecto de LaTeX a Typst.

Oleafly incluye Typst 0.15.1 y el servidor de lenguaje Tinymist 0.15.8, así que un proyecto de Typst nuevo compila sin que tengas que instalar nada. Esta página trata lo que puedes cambiar: qué Typst usa un proyecto, de dónde vienen sus paquetes y sus tipografías, y cómo un mismo código genera más de un PDF. Para la sintaxis y la barra de herramientas, empieza con [Escribe en Typst](/docs/writing/typst/).

## Versiones de Typst

Abre **Ajustes → Motores → Typst**. La primera tarjeta es **Typst (incluido)**, la versión que viene con la app. Si ya hay un `typst` instalado en tu ordenador, en tu `PATH`, en la carpeta de Homebrew o en `~/.cargo/bin`, una segunda tarjeta lo muestra como **Typst de este equipo**. Los proyectos que fijan exactamente esa versión pueden compilar con él.

Debajo, **Versiones** enumera Typst de la 0.11 a la 0.15, de la más reciente a la más antigua. Cada fila indica la fecha de publicación, el tamaño de la descarga, de dónde viene la copia (**Incluida**, **Descargada** o **Sistema**) y, una vez instalada, la versión de Tinymist que usa.

- **Instalar** descarga esa versión. Oleafly prueba primero con su propio espejo y después con GitHub, y comprueba el archivo y el programa que contiene con sumas de comprobación SHA-256 incorporadas a la app. Un archivo que no coincide se descarta, y una instalación fallida o cancelada no deja nada. Las descargas se guardan en `~/.oleafly/toolchains/typst/`.
- El botón redondo a la izquierda de una fila instalada convierte esa versión en la predeterminada.
- **Quitar** elimina una versión descargada. La predeterminada no se puede quitar, así que elige antes otra como predeterminada.

### La versión predeterminada y las versiones fijadas de los proyectos

Los proyectos de Typst nuevos fijan la versión predeterminada. También lo hacen los proyectos creados a partir de una plantilla, los proyectos importados y las carpetas enlazadas. La versión fijada se guarda en el `project.json` del proyecto como un número de versión, no como una ruta, así que sigue funcionando después de mover el proyecto o de abrirlo en otro ordenador.

Cambiar la versión predeterminada más adelante no mueve los proyectos existentes. Es deliberado: un artículo con la versión fijada conserva los mismos saltos de línea y el mismo número de páginas cuando Oleafly incorpora un Typst más reciente.

Para cambiar la versión de un proyecto, abre la flecha que hay junto a **Recompilar** y busca **Versión de Typst (este proyecto)**. **Predeterminada** sigue la versión elegida en Ajustes y quita la versión fijada. Las demás entradas son las versiones instaladas en este ordenador, marcadas con **[incluido]** o **[sistema]** cuando corresponde. Para usar una versión que no aparece en la lista, instálala antes en Ajustes.

### Cuando falta una versión fijada

Si abres un proyecto que fija una versión que este ordenador no tiene, Oleafly no lo compilará en silencio con otro Typst. La compilación se detiene con «Typst 0.13.1 no está instalado» y la vista previa ofrece dos botones:

- **Descargar Typst 0.13.1** instala la versión fijada y vuelve a compilar. Aparece cuando la versión es una de las que ofrece Oleafly.
- **Usar Typst 0.15.1**, con el nombre de tu versión predeterminada, quita la versión fijada y vuelve a compilar con la predeterminada.

El menú de compilación marca la versión fijada como **[no instalado]** hasta que elijas uno de los dos.

### Prueba una versión más reciente antes de cambiar

Con un proyecto de Typst abierto, la pestaña Typst de Ajustes muestra **Probar una versión más reciente** siempre que haya instalado un Typst más reciente. Elige **Comprobar con Typst 0.15.1** (o la versión que indique). Oleafly compila el proyecto dos veces en carpetas temporales, una con la versión actual del proyecto y otra con la más reciente. No cambia nada en tu proyecto.

El informe muestra si cada compilación tuvo éxito, su número de páginas y sus errores y advertencias. Te avisa si el número de páginas cambia. **Nuevo en Typst 0.15.1** enumera los mensajes que solo indica la versión más reciente, y **Typst 0.15.1 ya no lo indica** enumera los que desaparecen. Haz clic en un mensaje para abrir su archivo en esa línea.

Si te gusta lo que ves, **Cambiar a Typst 0.15.1** fija el proyecto en la versión más reciente. **Volver a comprobar** repite las dos compilaciones después de que corrijas algo.

### El servidor de lenguaje sigue la versión

Tinymist ofrece el autocompletado, la ayuda al pasar el cursor, el cambio de nombre y el formato en los archivos de Typst (consulta [Inteligencia de código](/docs/code-intelligence/#typst-files)). Cada versión menor de Typst tiene su propia versión de Tinymist, y un proyecto se comunica con la que corresponde a su versión de Typst.

El Tinymist incluido cubre Typst 0.15. Cuando abres un proyecto con la versión fijada en una línea anterior, Oleafly descarga en segundo plano el Tinymist correspondiente, con la misma comprobación de sumas, y el estado indica «Descargando Tinymist 0.13.30 para que coincida con la versión de Typst de este proyecto.» Si la descarga falla, Oleafly lo intenta de nuevo más tarde. Cuando Ajustes encuentra descargas de Tinymist que ya no necesita ningún Typst instalado, ofrece **Quitar las descargas del servidor de lenguaje sin usar**.

### Qué puede hacer cada versión

Las versiones más antiguas existen para que los proyectos iniciados con ellas sigan compilando igual. Algunas funciones dependen de lo que admita la propia versión de Typst:

| Función | 0.11 | 0.12 | 0.13 | 0.14 y posteriores |
| --- | --- | --- | --- | --- |
| Solo tipografías del proyecto | No | Sí | Sí | Sí |
| Compilación reproducible | No | Sí | Sí | Sí |
| Intervalos de páginas en la exportación a PNG y SVG | No | Sí | Sí | Sí |
| PDF/A | No | PDF/A-2b | PDF/A-2b, PDF/A-3b | Todos los niveles de PDF/A que ofrece Typst |
| PDF/UA-1 | No | No | No | Sí |
| Paquetes guardados en la carpeta del proyecto | No | Sí | Sí | Sí |
| Exportación a HTML, y a Word o Markdown a través del HTML de Typst | No | No | Sí | Sí |
| [Sincronización entre el código y el PDF](/docs/synctex/) | No | No | Sí | Sí |
| PDF etiquetado en cada compilación | No | No | No | Sí |

El selector de tipografías puede indicar de dónde viene cada tipografía en Typst 0.15 y posteriores. Cuando un ajuste no puede aplicarse a la versión que usa un proyecto, el menú de compilación lo marca con **Necesita un Typst más reciente**.

## Paquetes de Typst Universe

Elige **Paquetes de Typst**, el icono de paquete en el extremo derecho de la barra de Typst. Busca en Typst Universe por nombre, palabra clave o categoría. Cada paquete muestra su última versión, y un paquete que necesita un Typst más reciente que el del proyecto lo indica: «Necesita Typst 0.14.0. Este proyecto usa Typst 0.13.1.»

**Insertar importación** escribe la línea `#import` al principio del archivo de Typst abierto. **Copiar importación** la pone, en cambio, en el portapapeles.

Typst descarga un paquete `@preview` la primera vez que una compilación lo importa y lo guarda en una caché que comparten todos los proyectos. La lista de paquetes también se guarda en caché. Sin conexión, el cuadro de diálogo muestra la última lista que obtuvo, con su fecha.

### Versiones más recientes

Cuando una importación nombra una versión anterior a la que hay en Typst Universe, su número de versión aparece subrayado con una pista como «cetz 0.4.2 está disponible. Esta importación usa 0.3.4.» La tarjeta de la pista ofrece **Actualizar a 0.4.2**, que cambia el número de versión en la importación. Lee el registro de cambios del paquete antes de aceptarlo, porque una versión nueva puede cambiar la forma de llamar al paquete. Al pasar el cursor por una importación también se ofrece **Abrir en Typst Universe**.

### Guarda los paquetes dentro del proyecto

En **Paquetes del proyecto**, dentro del mismo cuadro de diálogo, **Incorporar los paquetes al proyecto** copia todos los paquetes que importa el proyecto en una carpeta `typst-packages` en la raíz del proyecto. También copia los paquetes que importan esos paquetes y activa **Usar paquetes de la carpeta del proyecto**.

A partir de entonces, Typst busca primero en `typst-packages`. Un proyecto con los paquetes incorporados compila sin conexión y en cualquier ordenador, y la carpeta puede ir a Git con tu código. Un paquete que no hayas incorporado sigue viniendo de la caché compartida. Esto necesita Typst 0.12 o posterior, y en un proyecto fijado a 0.11 el diálogo te pide que cambies de versión primero.

Si un paquete todavía no está en la caché, el cuadro de diálogo lo nombra: «Estos paquetes no están en la caché de paquetes: …». Compila una vez con conexión y vuelve a incorporarlos.

### Modo sin conexión

Con **Modo sin conexión** activado en **Ajustes → General**, Typst no puede descargar nada. Todos los paquetes tienen que estar ya en la caché compartida o en `typst-packages`. Si alguno no está, la compilación falla y el mensaje nombra el paquete, para que sepas qué obtener la próxima vez que tengas conexión.

## Tipografías

Typst encuentra las tipografías en cuatro lugares: las tipografías incluidas en Typst, las tipografías instaladas en tu ordenador, los paquetes de tipografías que descargas en Oleafly y las carpetas de tipografías dentro del proyecto. Pon los archivos de tipografías en una carpeta llamada `fonts` en la raíz del proyecto, y tanto el compilador como el servidor de lenguaje las recogerán. Puedes enumerar carpetas adicionales en `typst.font_paths`, dentro de `project.json`. Las carpetas de fuera del proyecto se ignoran.

En **Tipografías (este proyecto)**, dentro del menú de compilación, **Usar las tipografías del sistema** es la opción predeterminada. **Solo tipografías del proyecto** impide que Typst lea las tipografías instaladas en este ordenador. Así el PDF sale igual en todas las máquinas, y si el documento pide una tipografía que el proyecto no incluye, te enteras en tu propio ordenador y no en el de un coautor.

Para elegir una tipografía del texto, abre **Ajustes del documento**, el icono de controles deslizantes de la barra de Typst, y haz clic en **Tipografía del texto**. La lista muestra todas las familias que Typst puede encontrar con los ajustes de tipografías actuales del proyecto. En Typst 0.15 y posteriores, cada familia lleva una etiqueta **Proyecto**, **Sistema**, **Paquete de fuentes** o **Incluida**. Elige una y elige **Aplicar**, y Oleafly la escribe en las reglas `#set` del documento.

### Paquetes de tipografías

**Ajustes → Descargas → Tipografías** ofrece cinco paquetes de tipografías gratuitos para Typst: **Chino, japonés y coreano**, **Texto clásico**, **Sans y serif modernas**, **Código** e **Iconos y emoji**. Cuando un paquete termina de descargarse, todos los proyectos de Typst pueden usar sus tipografías por nombre, y lo mismo vale para las descargas de Lato, PT Sans y PT Serif de esa pestaña. Un paquete solo entra en las compilaciones cuando su descarga ha terminado por completo, así que una descarga a medias nunca afecta a una compilación.

Los proyectos con **Solo tipografías del proyecto** o **Compilación reproducible** no leen los paquetes de tipografías. Para esos, copia el archivo de la tipografía en la carpeta `fonts` del proyecto.

### Caracteres que se ven como cuadros

Después de cada compilación, Oleafly busca caracteres que ninguna tipografía disponible pudo dibujar. Typst los dibuja como cuadros. Cuando encuentra alguno, la compilación recibe una advertencia y aparece un aviso sobre el editor:

- Los **cuadros vacíos** significan que ninguna tipografía que Typst pueda usar tiene los caracteres, y la advertencia nombra algunos. Cuando un paquete de tipografías los cubre, como el de chino, japonés y coreano para el texto CJK y el de iconos y emoji para los emoji, el aviso ofrece **Descargar fuentes** con el tamaño de la descarga, y el registro ofrece **Descargar y compilar**. Si no, añade una tipografía que los tenga a la carpeta `fonts` del proyecto.
- Los **cuadros con un signo de interrogación** significan que Typst dibujó los caracteres con una tipografía provisional. Indica una tipografía que los tenga en **Tipografía del texto**, dentro de **Ajustes del documento**, o en una lista de tipografías como `#set text(font: ("Libertinus Serif", "Apple SD Gothic Neo"))`.
- En un proyecto con **Solo tipografías del proyecto**, los paquetes de tipografías y las tipografías del sistema no se aplican. Añade una tipografía a la carpeta `fonts`, o cambia el proyecto a **Usar las tipografías del sistema** y **Compilación estándar**.

**Ajustes del documento**, en el aviso, abre el panel donde eliges la tipografía del texto. Cierra el aviso para ocultarlo para esa advertencia.

## Variantes de compilación y sys.inputs

Una variante de compilación es un conjunto con nombre de valores que tu documento lee a través de `sys.inputs`. Usa las variantes cuando un mismo código deba producir PDF distintos, como una copia anónima para revisión y una copia final lista para imprenta, o un borrador con marca de agua.

El documento decide qué hace cada valor. Los valores siempre llegan como texto:

```typst
#let draft = sys.inputs.at("draft", default: "false") == "true"

#if draft [*Draft. Do not circulate.*]
```

Para preparar una variante:

1. Abre **Ajustes del documento** y desplázate hasta **Variantes de compilación**.
2. Elige **Añadir variante** y ponle un nombre, por ejemplo `review`.
3. Elige **Añadir valor** y escribe `draft` en **Nombre** y `true` en **Valor**.
4. Elige **Aplicar**.
5. Abre el menú de compilación. **Variante (este proyecto)** ahora enumera `review`. Elígela y compila.

**Sin variante** compila sin ningún valor de variante. La variante que elijas se recuerda solo en este ordenador, así que un coautor puede compilar otra distinta del mismo proyecto. Las variantes en sí se guardan en `project.json`. Las exportaciones también usan la variante seleccionada.

Los valores que deba recibir toda compilación van en `typst.inputs`, dentro de `project.json`. Cuando una variante define un valor con el mismo nombre, gana la variante.

## Compilaciones reproducibles

En **Compilación (este proyecto)**, dentro del menú de compilación, **Compilación reproducible** hace que el mismo código dé el mismo PDF en cualquier ordenador. Usa solo las tipografías del proyecto y las incluidas en Typst, y fecha el PDF con la última confirmación de Git. Un proyecto que no es un repositorio de Git recibe una fecha fija, el 1 de enero de 1970.

Esto importa cuando un PDF debe coincidir con una suma de comprobación, para un depósito en un archivo o una comparación en CI. Necesita Typst 0.12 o posterior. Mientras está activada, **Usar las tipografías del sistema** no está disponible. **Compilación estándar** es la opción predeterminada.

![Typst compila mientras escribes: cada línea nueva aparece en el PDF.](https://cdn.oleafly.com/images/gifs/desktop/typst-live.gif?v=2)

## Vista previa en vivo con la compilación automática

Pon **Compilación automática** en **Activada** en el menú de compilación. En un proyecto de Typst, Oleafly mantiene entonces un proceso de Typst en marcha. El archivo abierto se guarda solo poco después de que dejes de escribir, Typst lo compila y la vista previa se recarga en la misma posición de desplazamiento. No hay un ajuste aparte para la vista previa en vivo: la compilación automática es la vista previa en vivo.

Mientras Typst arranca, el menú muestra «Iniciando Typst». Si se detiene tras varios errores seguidos, el menú lo indica y tu siguiente edición lo vuelve a iniciar. **Detener la compilación** termina el proceso, y la siguiente edición también lo vuelve a iniciar. Los proyectos de LaTeX y de Markdown gestionan la compilación automática de otra forma; consulta [Compilación](/docs/compiling/#auto-compile).

## Compila desde la línea de comandos

El comando `oleafly` compila proyectos sin abrir la app. Viene con Oleafly, y [Herramienta de línea de comandos](/docs/cli/#install) explica cómo ponerlo en tu PATH.

En un proyecto de Typst, `oleafly build` y `oleafly watch` leen `project.json` y usan los mismos ajustes que la app: la versión fijada, los paquetes incorporados, las carpetas de tipografías, el interruptor de las tipografías del sistema, las entradas y las compilaciones reproducibles.

- `--variant review` compila una variante. Un nombre que el proyecto no define detiene la compilación, y el mensaje enumera las variantes que sí tiene.
- `--offline` bloquea las descargas de paquetes, como el modo sin conexión de la app.
- Un proyecto con versión fijada solo compila con ese Typst exacto. La CLI busca `OLEAFLY_TYPST`, después las versiones que descargó la app, luego el `typst` que hay junto a la CLI y por último tu `PATH`. Si ninguno indica la versión fijada, la compilación se detiene antes de ejecutar Typst y te dice cómo instalarla.
- Un proyecto sin versión fijada usa `OLEAFLY_TYPST` cuando está definida. Si no, usa la versión predeterminada que elegiste en **Ajustes → Descargas** o con `oleafly typst default` y, si no elegiste ninguna, el Typst incluido o el de tu `PATH`.
- `oleafly doctor` enumera todos los Typst que encontró y los ajustes que usaría una compilación. Falla cuando falta la versión fijada.

Si un ajuste no puede aplicarse al Typst que se está usando, la compilación imprime una nota, por ejemplo que Typst 0.11.1 no puede ignorar las tipografías del sistema. Los errores del terminal incluyen las propias pistas de Typst.

## Convierte un proyecto de LaTeX a Typst

Abre el proyecto de LaTeX, pulsa ⌘K (Ctrl+K) y ejecuta **Convertir en un proyecto de Typst**. Ponle un nombre al proyecto nuevo y elige **Convertir**. El proyecto de LaTeX se queda exactamente como estaba. Oleafly crea a partir de él un proyecto de Typst aparte:

- Pandoc convierte el texto, las fórmulas, las figuras y las tablas. Si Pandoc todavía no está configurado, Oleafly lo configura primero.
- Cada archivo incorporado con `\input`, `\include` o `\subfile` pasa a ser su propio archivo `.typ`.
- Los archivos BibTeX se copian sin cambios.
- Typst compila el proyecto nuevo para comprobarlo.

Después, el informe indica si el proyecto compila y cuenta lo que se convirtió: archivos de código, figuras, tablas, ecuaciones en bloque, referencias cruzadas, fórmulas que reparó el conversor de fórmulas y archivos copiados, junto con el estilo de bibliografía que eligió. **Necesita atención** enumera lo que hay que arreglar a mano, como un include o una imagen que faltan, un formato de imagen que Typst no puede mostrar, fórmulas que el conversor no pudo tratar, un estilo de BibTeX sin equivalente en Typst o una etiqueta en una línea de una ecuación de varias líneas, que ahora apunta a toda la ecuación. Los errores y las advertencias de compilación enlazan con su archivo y su línea.

Elige **Abrir el proyecto de Typst** para pasar a él. El proyecto nuevo fija tu versión predeterminada de Typst. Mientras Oleafly siga abierto, **Mostrar el informe de conversión a Typst** en la paleta de comandos recupera el informe.

Para convertir un solo archivo en lugar de un proyecto entero, usa [De LaTeX a Typst](/docs/tools/latex-to-typst/) en la página de Herramientas.

## Páginas relacionadas

- [Escribe en Typst](/docs/writing/typst/) para la barra de herramientas y un primer documento.
- [Compilación](/docs/compiling/) para los registros, el menú de compilación y el modo sin conexión.
- [Exporta y convierte un proyecto](/docs/export/#typst-images-and-html) para PNG, SVG, HTML, PDF/A y PDF/UA.
- [Comprobaciones de Preflight](/docs/preflight/#typst-projects) para las comprobaciones que leen código de Typst.
