# Projets Typst

Épinglez une version de Typst par projet, ajoutez des paquets de Typst Universe, contrôlez les polices, les variantes de compilation et les PDF reproductibles, et convertissez un projet LaTeX en Typst.

Oleafly est fourni avec Typst 0.15.1 et le serveur de langage Tinymist 0.15.8, donc un nouveau projet Typst compile sans rien à installer. Cette page couvre ce que vous pouvez changer : quel Typst un projet utilise, d'où viennent ses paquets et ses polices, et comment une seule source produit plus d'un PDF. Pour la syntaxe et la barre d'outils, commencez par [Écrire en Typst](/docs/writing/typst/).

## Versions de Typst

Ouvrez **Paramètres → Moteurs → Typst**. La première carte est **Typst (intégré)**, la version fournie avec l'application. Si un `typst` est déjà installé sur votre ordinateur, sur votre `PATH`, dans le dossier de Homebrew ou dans `~/.cargo/bin`, une seconde carte l'affiche comme **Typst sur cet ordinateur**. Les projets qui épinglent cette version exacte peuvent compiler avec elle.

En dessous, **Versions** liste Typst 0.11 à 0.15, la plus récente en premier. Chaque ligne donne la date de publication, la taille du téléchargement, la provenance de la copie (**Intégrée**, **Téléchargée** ou **Système**) et, une fois installée, la version de Tinymist qu'elle utilise.

- **Installer** télécharge cette version. Oleafly essaie d'abord son propre miroir puis GitHub, et vérifie l'archive et le programme qu'elle contient par rapport à des sommes de contrôle SHA-256 intégrées dans l'application. Un fichier qui ne correspond pas est jeté, et une installation échouée ou annulée ne laisse rien derrière elle. Les téléchargements vivent dans `~/.oleafly/toolchains/typst/`.
- Le bouton rond à gauche d'une ligne installée définit cette version comme valeur par défaut.
- **Supprimer** efface une version téléchargée. La version par défaut ne peut pas être supprimée, donc choisissez d'abord une autre valeur par défaut.

### La version par défaut et les épingles de projet

Les nouveaux projets Typst épinglent la version par défaut. Il en va de même des projets créés depuis un modèle, des projets importés et des dossiers liés. Une épingle est enregistrée dans le `project.json` du projet sous forme de numéro de version, pas de chemin, donc elle fonctionne toujours après un déplacement du projet ou une ouverture sur un autre ordinateur.

Changer la version par défaut plus tard ne déplace pas les projets existants. C'est délibéré : un article épinglé conserve les mêmes coupures de ligne et le même nombre de pages quand Oleafly livre un Typst plus récent.

Pour changer la version d'un projet, ouvrez la flèche à côté de **Recompiler** et regardez sous **Version de Typst (ce projet)**. **Par défaut** suit la version choisie dans les Paramètres et retire l'épingle. Les autres entrées sont les versions installées sur cet ordinateur, marquées **[intégré]** ou **[système]** le cas échéant. Pour utiliser une version qui n'est pas listée, installez-la d'abord dans les Paramètres.

### Quand une version épinglée manque

Si vous ouvrez un projet qui épingle une version que cet ordinateur n'a pas, Oleafly ne le compilera pas en silence avec un autre Typst. La compilation s'arrête avec « Typst 0.13.1 n'est pas installé », et l'aperçu propose deux boutons :

- **Télécharger Typst 0.13.1** installe la version épinglée et compile à nouveau. Il apparaît quand la version fait partie de celles qu'Oleafly propose.
- **Utiliser Typst 0.15.1**, nommé d'après votre version par défaut, retire l'épingle et compile à nouveau avec la version par défaut.

Le menu de compilation marque l'épingle **[non installé]** jusqu'à ce que vous en choisissiez un.

### Essayer une version plus récente avant de changer

Avec un projet Typst ouvert, l'onglet Typst des Paramètres affiche **Essayer une version plus récente** chaque fois qu'un Typst plus récent est installé. Choisissez **Vérifier avec Typst 0.15.1** (ou la version qu'il nomme). Oleafly compile le projet deux fois dans des dossiers temporaires, une fois avec la version actuelle du projet et une fois avec la plus récente. Rien dans votre projet ne change.

Le rapport indique si chaque compilation a réussi, son nombre de pages, et ses erreurs et avertissements. Il vous dit si le nombre de pages change. **Nouveau avec Typst 0.15.1** liste les messages que seule la version plus récente signale, et **Plus signalé par Typst 0.15.1** liste ceux qui disparaissent. Cliquez sur un message pour ouvrir son fichier à cette ligne.

Si le résultat vous convient, **Passer à Typst 0.15.1** épingle le projet sur la version plus récente. **Vérifier à nouveau** relance les deux compilations après une correction.

### Le serveur de langage suit la version

Tinymist alimente la complétion, l'aide au survol, le renommage et le formatage dans les fichiers Typst (voir [Intelligence du code](/docs/code-intelligence/#typst-files)). Chaque version mineure de Typst a sa propre version de Tinymist, et un projet dialogue avec celle qui correspond à sa version de Typst.

Le Tinymist intégré couvre Typst 0.15. Quand vous ouvrez un projet épinglé sur une ligne plus ancienne, Oleafly télécharge le Tinymist correspondant en arrière-plan, avec la même vérification de somme de contrôle, et l'état affiche « Téléchargement de Tinymist 0.13.30 pour correspondre à la version de Typst de ce projet. » Si le téléchargement échoue, Oleafly réessaie plus tard. Quand les Paramètres trouvent des téléchargements de Tinymist dont plus aucun Typst installé n'a besoin, ils proposent **Supprimer les téléchargements de serveur de langage inutilisés**.

### Ce que chaque version peut faire

Les versions plus anciennes existent pour que les projets commencés dessus continuent de compiler de la même façon. Certaines fonctions dépendent de ce que la version de Typst elle-même prend en charge :

| Fonctionnalité | 0.11 | 0.12 | 0.13 | 0.14 et plus récent |
| --- | --- | --- | --- | --- |
| Polices du projet uniquement | Non | Oui | Oui | Oui |
| Compilation reproductible | Non | Oui | Oui | Oui |
| Plages de pages dans l'export PNG et SVG | Non | Oui | Oui | Oui |
| PDF/A | Non | PDF/A-2b | PDF/A-2b, PDF/A-3b | Tous les niveaux de PDF/A que Typst offre |
| PDF/UA-1 | Non | Non | Non | Oui |
| Paquets conservés dans le dossier du projet | Non | Oui | Oui | Oui |
| Export HTML, et export Word ou Markdown via le HTML de Typst | Non | Non | Oui | Oui |
| [Synchronisation source et PDF](/docs/synctex/) | Non | Non | Oui | Oui |
| PDF balisé à chaque compilation | Non | Non | Non | Oui |

Le sélecteur de polices peut indiquer d'où vient chaque police sur Typst 0.15 et plus récent. Quand un réglage ne peut pas s'appliquer à la version qu'un projet utilise, le menu de compilation le marque **Nécessite un Typst plus récent**.

## Paquets de Typst Universe

Choisissez **Paquets Typst**, l'icône de paquet à l'extrémité droite de la barre d'outils Typst. Cherchez dans Typst Universe par nom, mot-clé ou catégorie. Chaque paquet affiche sa dernière version, et un paquet qui exige un Typst plus récent que celui du projet le dit : « Nécessite Typst 0.14.0. Ce projet utilise Typst 0.13.1. »

**Insérer l'import** écrit la ligne `#import` en haut du fichier Typst ouvert. **Copier l'import** la place dans le presse-papiers à la place.

Typst télécharge un paquet `@preview` la première fois qu'une compilation l'importe et le conserve dans un cache que tous les projets partagent. La liste des paquets est aussi mise en cache. Hors ligne, la boîte de dialogue affiche la dernière liste récupérée, avec sa date.

### Versions plus récentes

Quand un import nomme une version plus ancienne que celle sur Typst Universe, son numéro de version est souligné avec une indication comme « cet 0.4.2 est disponible. Cet import utilise 0.3.4. » La carte d'indication propose **Mettre à jour vers 0.4.2**, qui change le numéro de version dans l'import. Lisez le journal des modifications du paquet avant d'accepter, parce qu'une nouvelle version peut changer la façon d'appeler le paquet. Survoler un import propose aussi **Ouvrir sur Typst Universe**.

### Garder les paquets dans le projet

Sous **Paquets du projet** dans la même boîte de dialogue, **Intégrer les paquets au projet** copie chaque paquet que le projet importe dans un dossier `typst-packages` à la racine du projet. Il copie aussi les paquets que ces paquets importent, et active **Utiliser les paquets du dossier du projet**.

Dès lors, Typst regarde d'abord dans `typst-packages`. Un projet avec paquets intégrés compile hors ligne et sur n'importe quel ordinateur, et le dossier peut partir dans Git avec votre source. Un paquet que vous n'avez pas intégré vient toujours du cache partagé. Cela demande Typst 0.12 ou plus récent, et sur un projet épinglé à 0.11, la boîte de dialogue vous demande d'abord de changer de version.

Si un paquet n'est pas encore dans le cache, la boîte de dialogue le nomme : « Ces paquets ne sont pas dans le cache des paquets : … ». Compilez une fois en ligne, puis intégrez à nouveau.

### Mode hors ligne

Avec le **Mode hors ligne** activé dans **Paramètres → Général**, Typst ne peut rien télécharger. Chaque paquet doit déjà être dans le cache partagé ou dans `typst-packages`. S'il en manque un, la compilation échoue et le message nomme le paquet, pour que vous sachiez quoi récupérer à votre prochaine connexion.

## Polices

Typst trouve les polices à quatre endroits : les polices intégrées à Typst, les polices installées sur votre ordinateur, les packs de polices que vous téléchargez dans Oleafly et les dossiers de polices à l'intérieur du projet. Placez des fichiers de polices dans un dossier nommé `fonts` à la racine du projet, et le compilateur comme le serveur de langage les prennent en charge. Des dossiers supplémentaires peuvent être listés sous `typst.font_paths` dans `project.json`. Les dossiers en dehors du projet sont ignorés.

Sous **Polices (ce projet)** dans le menu de compilation, **Utiliser les polices système** est la valeur par défaut. **Polices du projet uniquement** empêche Typst de lire les polices installées sur cet ordinateur. Le PDF sort alors identique sur chaque machine, et si le document demande une police que le projet n'inclut pas, vous l'apprenez sur votre propre ordinateur plutôt que sur celui d'un coauteur.

Pour choisir une police du texte, ouvrez **Réglages du document**, l'icône de curseurs de la barre d'outils Typst, et cliquez sur **Police du texte**. La liste affiche chaque famille que Typst peut trouver avec les réglages de polices actuels du projet. Sur Typst 0.15 et plus récent, chaque famille porte une étiquette **Projet**, **Système**, **Pack de polices** ou **Intégrée**. Choisissez-en une, choisissez **Appliquer**, et Oleafly l'écrit dans les règles `#set` du document.

### Packs de polices

**Paramètres → Téléchargements → Polices** propose cinq packs de polices gratuits pour Typst : **Chinois, japonais et coréen**, **Texte classique**, **Sans et serif modernes**, **Code**, et **Icônes et emoji**. Une fois un pack téléchargé, chaque projet Typst peut utiliser ses polices par leur nom, et il en va de même pour les téléchargements Lato, PT Sans et PT Serif de cet onglet. Un pack ne rejoint les compilations qu'une fois son téléchargement entièrement terminé, si bien qu'un téléchargement inachevé n'affecte jamais une compilation.

Les projets réglés sur **Polices du projet uniquement** ou **Compilation reproductible** ne lisent pas les packs de polices. Pour ceux-là, copiez le fichier de police dans le dossier `fonts` du projet.

### Caractères qui s'affichent en cases

Après chaque compilation, Oleafly cherche les caractères qu'aucune police disponible ne pouvait dessiner. Typst les dessine sous forme de cases. S'il en trouve, la compilation reçoit un avertissement et un avis apparaît au-dessus de l'éditeur :

- **Les cases vides** signifient qu'aucune police que Typst peut utiliser ne contient ces caractères, et l'avertissement en nomme quelques-uns. Quand un pack de polices les couvre, comme le pack Chinois, japonais et coréen pour le texte CJK et le pack Icônes et emoji pour les emoji, l'avis propose **Télécharger les polices** avec la taille du téléchargement, et le journal propose **Télécharger et compiler**. Sinon, ajoutez au dossier `fonts` du projet une police qui les contient.
- **Les cases avec un point d'interrogation** signifient que Typst a dessiné les caractères avec une police de remplacement. Nommez une police qui les contient sous **Police du texte** dans **Réglages du document**, ou dans une liste de polices comme `#set text(font: ("Libertinus Serif", "Apple SD Gothic Neo"))`.
- Dans un projet réglé sur **Polices du projet uniquement**, les packs de polices et les polices système ne s'appliquent pas. Ajoutez une police au dossier `fonts`, ou passez le projet sur **Utiliser les polices système** et **Compilation standard**.

**Réglages du document**, dans l'avis, ouvre le panneau où vous choisissez la police du texte. Fermer l'avis le masque pour cet avertissement.

## Variantes de compilation et sys.inputs

Une variante de compilation est un jeu de valeurs nommé que votre document lit à travers `sys.inputs`. Utilisez des variantes quand une seule source doit produire des PDF différents, comme une copie anonymisée pour évaluation et une copie finale prête à publier, ou un brouillon avec filigrane.

Le document décide ce que fait chaque valeur. Les valeurs arrivent toujours sous forme de texte :

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

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

Pour créer une variante :

1. Ouvrez **Réglages du document** et faites défiler jusqu'à **Variantes de compilation**.
2. Choisissez **Ajouter une variante** et nommez-la, par exemple `review`.
3. Choisissez **Ajouter une valeur**, puis saisissez `draft` sous **Nom** et `true` sous **Valeur**.
4. Choisissez **Appliquer**.
5. Ouvrez le menu de compilation. **Variante (ce projet)** liste maintenant `review`. Choisissez-la et compilez.

**Aucune variante** compile sans aucune valeur de variante. La variante que vous choisissez est mémorisée sur cet ordinateur uniquement, donc un coauteur peut en compiler une autre depuis le même projet. Les variantes elles-mêmes sont enregistrées dans `project.json`. Les exports utilisent aussi la variante sélectionnée.

Les valeurs que chaque compilation devrait recevoir vont sous `typst.inputs` dans `project.json`. Quand une variante définit une valeur du même nom, la variante gagne.

## Compilations reproductibles

Sous **Compilation (ce projet)** dans le menu de compilation, **Compilation reproductible** fait en sorte que les mêmes sources donnent le même PDF sur n'importe quel ordinateur. Elle n'utilise que les polices du projet et les polices intégrées de Typst, et date le PDF du dernier commit Git. Un projet qui n'est pas un dépôt Git reçoit une date fixe au 1er janvier 1970.

Cela compte quand un PDF doit correspondre à une somme de contrôle, pour un dépôt d'archive ou une comparaison en CI. Il faut Typst 0.12 ou plus récent. Pendant qu'elle est active, **Utiliser les polices système** est indisponible. **Compilation standard** est la valeur par défaut.

![Typst compile pendant la frappe : chaque nouvelle ligne apparaît dans le PDF.](https://cdn.oleafly.com/images/gifs/desktop/typst-live.gif?v=2)

## Aperçu en direct avec la compilation automatique

Réglez **Compilation automatique** sur **Activée** dans le menu de compilation. Dans un projet Typst, Oleafly garde alors un processus Typst actif. Le fichier ouvert s'enregistre de lui-même un instant après que vous avez cessé de taper, Typst le compile, et l'aperçu se recharge à la même position de défilement. Il n'existe pas de réglage d'aperçu en direct distinct : la compilation automatique est l'aperçu en direct.

Pendant que Typst démarre, le menu affiche « Démarrage de Typst ». S'il s'arrête après des erreurs répétées, le menu le dit, et votre prochaine modification le relance. **Arrêter la compilation** met fin au processus, et la modification suivante le relance aussi. Les projets LaTeX et Markdown traitent la compilation automatique différemment ; voir [Compiler](/docs/compiling/#auto-compile).

## Compiler depuis la ligne de commande

La commande `oleafly` compile des projets sans ouvrir l'application. Elle est fournie avec Oleafly, et [Outil en ligne de commande](/docs/cli/#install) montre comment la mettre sur votre PATH.

Pour un projet Typst, `oleafly build` et `oleafly watch` lisent `project.json` et utilisent les mêmes réglages que l'application : la version épinglée, les paquets intégrés, les dossiers de polices, le commutateur des polices système, les entrées et les compilations reproductibles.

- `--variant review` compile une variante. Un nom que le projet ne définit pas arrête la compilation, et le message liste les variantes qu'il possède.
- `--offline` bloque les téléchargements de paquets, comme le mode hors ligne dans l'application.
- Un projet épinglé ne compile qu'avec ce Typst exact. Le CLI regarde `OLEAFLY_TYPST`, puis les versions téléchargées par l'application, puis le `typst` à côté du CLI, puis votre `PATH`. Si aucun ne rapporte la version épinglée, la compilation s'arrête avant que Typst ne tourne et vous dit comment l'installer.
- Un projet sans épingle utilise `OLEAFLY_TYPST` s'il est défini. Sinon, il utilise la version par défaut que vous avez choisie dans **Paramètres → Téléchargements** ou avec `oleafly typst default`, et, sans version par défaut choisie, le Typst intégré ou celui de votre `PATH`.
- `oleafly doctor` liste chaque Typst trouvé et les réglages qu'une compilation utiliserait. Il échoue quand la version épinglée manque.

Si un réglage ne peut pas s'appliquer au Typst utilisé, la compilation affiche une note, par exemple que Typst 0.11.1 ne peut pas ignorer les polices système. Les erreurs dans le terminal incluent les propres indications de Typst.

## Convertir un projet LaTeX en Typst

Ouvrez le projet LaTeX, appuyez sur ⌘K (Ctrl+K) et lancez **Convertir en projet Typst**. Donnez un nom au nouveau projet et choisissez **Convertir**. Le projet LaTeX reste exactement comme il était. Oleafly en construit un projet Typst distinct :

- Pandoc convertit le texte, les maths, les figures et les tableaux. Si Pandoc n'est pas encore installé, Oleafly l'installe d'abord.
- Chaque fichier introduit avec `\input`, `\include` ou `\subfile` devient son propre fichier `.typ`.
- Les fichiers BibTeX sont copiés sans changement.
- Typst compile le nouveau projet pour le vérifier.

Le rapport dit ensuite si le projet compile et compte ce qui a été converti : fichiers sources, figures, tableaux, équations hors texte, renvois, formules réparées par le convertisseur mathématique et fichiers copiés, avec le style de bibliographie qu'il a choisi. **Action requise** liste ce qu'il faut corriger à la main, comme un include ou une image manquants, un format d'image que Typst ne peut pas afficher, des maths que le convertisseur n'a pas pu traiter, un style BibTeX sans équivalent Typst, ou un libellé sur une ligne d'une équation multiligne, qui pointe maintenant vers l'équation entière. Les erreurs et avertissements de compilation mènent à leur fichier et à leur ligne.

Choisissez **Ouvrir le projet Typst** pour y passer. Le nouveau projet épingle votre version de Typst par défaut. Pendant qu'Oleafly reste ouvert, **Afficher le rapport de conversion Typst** dans la palette de commandes ramène le rapport.

Pour convertir un seul fichier plutôt qu'un projet entier, utilisez [LaTeX vers Typst](/docs/tools/latex-to-typst/) sur la page Outils.

## Pages liées

- [Écrire en Typst](/docs/writing/typst/) pour la barre d'outils et un premier document.
- [Compiler](/docs/compiling/) pour les journaux, le menu de compilation et le mode hors ligne.
- [Exporter et convertir un projet](/docs/export/#typst-images-and-html) pour PNG, SVG, HTML, PDF/A et PDF/UA.
- [Contrôles de prévérification](/docs/preflight/#typst-projects) pour les contrôles qui lisent les sources Typst.
