Écrire en Typst

Choisissez un modèle Typst et modifiez son source .typ à côté du PDF compilé. La barre d’outils écrit la syntaxe Typst pour vous, si bien que chaque modification reste dans le source, où vous pouvez la lire et la modifier. Quand vous préférez ne pas regarder le balisage, basculez le fichier en mode Visuel.

L'exemple Typst avec sa barre de mise en forme, son source et le rapport compilé. Ouvrir la capture complète

Compiler un petit rapport

1. Choisissez Nouveau projet → Utiliser un modèle → Blank Typst document.
2. Nommez le projet Note de mesures et ouvrez main.typ.
3. Collez l’exemple ci-dessous, puis choisissez Recompiler ou appuyez sur ⌘Enter / Ctrl+Enter.

main.typ

#set document(title: "Measurement note", author: "Alex Chen")
#set page(paper: "a4", margin: 25mm)
#set heading(numbering: "1.")

= Measurement note
A short report on repeated measurements.

== Method <method>
We collect three observations and compare their mean.

$ overline(x) = (1 + 2 + 3) / 3 = 2 $

== Results
See @method for the procedure.

#table(
  columns: 2,
  [Run], [Value],
  [1], [1],
  [2], [2],
  [3], [3],
)

Le PDF doit afficher des titres numérotés, une équation hors ligne, un renvoi à la méthode et un tableau à deux colonnes.

Pour voir le PDF changer pendant la saisie, ouvrez la flèche à côté de Recompiler et réglez Compilation automatique sur Activée. Dans un projet Typst, c’est l’aperçu en direct. Voir Aperçu en direct avec la compilation automatique.

Télécharger le source de l’exemple

Chaque outil de la barre d’outils

Sélectionnez du texte avant d’utiliser un outil de mise en forme, pour l’entourer. Sans sélection, la barre d’outils insère un espace réservé dans lequel vous pouvez saisir. Quand l’éditeur est trop étroit pour tous les boutons, ceux qui ne tiennent pas passent dans Plus d’options de mise en forme (…). La plupart de ces outils figurent aussi dans le menu contextuel de l’éditeur.

Code / Visuel

Le commutateur au début de la barre d’outils change la façon dont le fichier est affiché. Code montre le source Typst. Visuel dessine les titres, les mises en valeur, les listes, les maths, les images, les tableaux, les renvois et les notes de bas de page à leur place, et ramène le source à la ligne où se trouve votre curseur. Le fichier est le même dans les deux modes. Le mode Visuel en Typst donne les détails.

Annuler

Annule votre dernière modification. ⌘Z / Ctrl+Z. Le bouton est grisé quand il n’y a rien à annuler.

Rétablir

Réapplique une modification annulée. ⌘Shift+Z / Ctrl+Shift+Z.

Titre → Titre

Sélectionnez un titre et choisissez Titre. = Title.

Titre → Section

Ajoute une section dans le document. == Section.

Titre → Sous-section

Ajoute un niveau sous une section. === Subsection.

Titre → Sous-sous-section

Ajoute un titre de quatrième niveau. ==== Subsubsection.

Titre → Titre mineur

Ajoute un titre de cinquième niveau. ===== Minor heading.

Titre → Titre de paragraphe

Ajoute un titre de sixième niveau. ====== Paragraph heading.

Gras

Sélectionnez « three observations ». *three observations* ; ⌘B / Ctrl+B.

Italique

Sélectionnez un terme à mettre en valeur. _term_ ; ⌘I / Ctrl+I.

Souligné

Sélectionnez une expression. #underline[phrase].

Barré

Marque une expression obsolète. #strike[phrase].

Code en ligne

Sélectionnez un nom de fichier ou de variable. L’entoure de backticks.

Insérer un lien

Remplacez url, puis text. #link("url")[text].

Citer depuis le projet

Cherchez dans la bibliographie du projet par clé, auteur ou titre, puis choisissez une entrée. Oleafly écrit @key. Si le document ne contient pas encore d’appel à #bibliography, Oleafly en ajoute un. Trouver et ajouter une nouvelle citation…, en bas de la liste, ouvre la recherche d’une nouvelle source. Voir Ajouter des citations.

Insérer un renvoi

Choisissez une étiquette dans la liste du projet pour écrire @label. Dans l’exemple, choisissez method pour obtenir @method. Ajouter une étiquette ici place plutôt une nouvelle étiquette sur l’élément au curseur.

Ajouter une étiquette

Placez le curseur dans un titre, une figure ou une équation et choisissez Ajouter une étiquette. Sur le titre Results de l’exemple, Oleafly ajoute <sec:results>. Si l’élément possède déjà une étiquette, le bouton la sélectionne.

Insérer une note de bas de page

Placez le curseur après un mot. #footnote[note text].

Insérer une citation en bloc

Placez le curseur sur une nouvelle ligne. #quote(block: true)[quote].

Insérer une figure

Ouvre la boîte de dialogue des figures. Choisissez une image dans Images du projet ou choisissez Importer depuis le disque…, puis définissez sa largeur, sa légende, son étiquette, son texte alternatif et son placement. Avec le curseur à l’intérieur d’un #figure existant, le même bouton ouvre Modifier la figure pour que vous puissiez changer n’importe lequel de ces réglages. Voir Ajouter une figure avec légende.

Insérer un tableau

Ouvrez la grille et choisissez le nombre de lignes et de colonnes. Oleafly insère un #figure contenant un table, avec une ligne d’en-tête et des filets haut, médian et bas, plus caption: [Caption] et l’étiquette <tab:label>. Remplacez la légende, l’étiquette et les cellules vides. Pour plutôt construire un tableau à partir d’un classeur, voir Tableaux depuis des fichiers de données.

Insérer une image

Importez une image, puis remplacez le nom de fichier sélectionné par son chemin relatif. #image("image-filename"). Vous pouvez aussi coller ou déposer un fichier image dans l’éditeur : Oleafly l’enregistre dans le projet et insère une figure qui l’utilise.

Dessiner un diagramme

Ouvre le compositeur de diagrammes en mode Typst. Dessinez sur le canevas ou modifiez le code fletcher, puis choisissez Insérer en Typst pour placer le diagramme au curseur. Le premier aperçu télécharge le paquet fletcher depuis Typst Universe : il faut donc être en ligne.

Image vers Typst

Choisissez la capture d’écran d’une équation ou d’un texte, et elle est transcrite en Typst au curseur. La transcription utilise le modèle pour les Outils, un modèle Ollama local sauf si vous en choisissez un autre. Si vous n’en avez pas choisi et qu’Ollama ne tourne pas ou n’a aucun modèle qui lit les images, elle utilise à la place le modèle de l’assistant, et l’image part vers ce fournisseur. Vérifiez le résultat et compilez-le.

Liste → Liste à puces

Démarre une liste d’observations. - Item.

Liste → Liste numérotée

Démarre une suite d’étapes. + Item.

Maths

Sélectionnez x et cliquez sur l’icône maths. $x$.

Équation hors ligne

Une équation sur sa propre ligne. $ x $, avec une espace à l’intérieur de chaque $.

Équation numérotée

Une équation hors ligne avec une étiquette, par exemple $ x $ <eq:label>. Typst numérote les équations seulement quand le document possède une règle de numérotation. Si le vôtre n’en a pas, une note propose Ajouter la règle, qui ajoute #set math.equation(numbering: "(1)") près du haut du fichier.

Équations alignées

Plusieurs équations alignées sur &, avec \ entre les lignes. $ a &= b \ c &= d $.

Fraction

Insère frac(a, b), encadré de $ quand le curseur n’est pas déjà en mode maths. Avec du texte sélectionné, la sélection devient le numérateur.

Symboles

Ouvrez le sélecteur de symboles, cherchez un symbole et sélectionnez-le. Oleafly l’écrit sous son nom Typst : arrow.r en mode maths, ou #sym.arrow.r dans le texte courant.

Bloc de code

Sélectionnez plusieurs lignes de code ou remplacez l’espace réservé. Un bloc encadré par trois backticks. Ajoutez un langage après la balise d’ouverture pour la coloration syntaxique.

Intelligence du code → Aller à la définition

Placez le curseur sur une étiquette, une variable ou une fonction et choisissez l’action, ou appuyez sur F12. Ouvre l’endroit où elle est définie, même dans un autre fichier.

Intelligence du code → Rechercher les références

Liste chaque endroit où une étiquette, une variable ou une fonction est utilisée. ⇧F12.

Intelligence du code → Renommer le symbole

Renomme une étiquette, une variable ou une fonction dans tout le projet. F2. Intelligence du code couvre les trois.

Paquets Typst

L’icône de paquet, à l’extrémité droite de la barre, cherche dans Typst Universe et insère une ligne #import. Plus de détails dans Paquets, réglages et analyse.

Analyse du document

Liste les titres, figures, tableaux, équations, étiquettes, citations et tâches à faire du document, chacun relié à sa ligne. Voir Analyse du document.

Réglages du document

Change la taille de page, les marges, la police, la langue, la justification, l’interligne et la numérotation en modifiant les règles #set du document. Voir Réglages du document.

Infos du projet

Affiche le nombre de mots, de figures et de maths du document et de toute sélection, plus les résultats de la relecture.

Rechercher

Cherche un mot dans le fichier actif. ⌘F / Ctrl+F.

Aller au PDF

Va du curseur à l’endroit correspondant dans le PDF compilé. Le bouton apparaît à partir de Typst 0.13. Voir Sauter entre le source et le PDF.

Le mode Visuel

Basculez la barre d’outils de Code à Visuel dans n’importe quel fichier .typ. Le mode Visuel est le même éditeur, avec le balisage dessiné à sa place :

• les titres, le texte en gras et en italique, le texte brut, les liens et le texte coloré
• les listes à puces, numérotées et de termes avec leurs marqueurs
• les maths en ligne et hors ligne, dessinées par Typst
• les images et les figures, avec la légende affichée en texte
• les tableaux sous forme de grille dans laquelle vous pouvez saisir. Sélectionnez une cellule pour faire apparaître une petite barre d’outils pour les bordures, l’alignement, les lignes et les colonnes.
• les renvois et les citations sous forme de pastilles, et les notes de bas de page sous forme de petit marqueur

Placez le curseur sur une ligne et son source revient pour que vous puissiez le modifier. Éloignez le curseur et la forme rendue revient. Les lignes #set, #show, #import et #let en haut du fichier se replient dans une barre Afficher les réglages du document, sur laquelle vous pouvez cliquer pour l’ouvrir. Tout ce que le mode Visuel ne peut pas dessiner reste à l’écran sous forme de source. Chaque bouton de la barre d’outils écrit le même Typst dans les deux modes, et les numéros de ligne, la recherche, l’orthographe et les erreurs de compilation continuent de fonctionner.

Les nouveaux projets s’ouvrent en mode Code, et chaque projet retient le mode dans lequel vous l’avez laissé. Édition visuelle couvre le basculement pour les trois langages.

L’aide pendant la saisie

Les fichiers Typst reçoivent les mêmes aides que les fichiers LaTeX, écrites pour la syntaxe Typst :

• Cliquez sur la flèche dans la gouttière pour replier un titre jusqu’au prochain titre de même niveau. Les blocs de code, les blocs de contenu, les équations et les longues listes d’arguments se replient aussi. Voir Pliage du code.
• Pendant le défilement, les titres au-dessus du curseur restent épinglés en haut de l’éditeur. Une barre de fil d’Ariane au-dessus du fichier nomme la section où vous vous trouvez, et un clic sur un élément du fil va au titre correspondant.
• Saisir $ ajoute le $ fermant, et une espace à l’intérieur de la paire vide la transforme en maths hors ligne. Sur un élément de liste, Enter démarre l’élément suivant. Aides à la saisie Typst liste le reste.
• Le serveur de langage Typst autocomplète les fonctions, les chemins de fichiers, les étiquettes, les clés de citation, les paquets et les styles de bibliographie. Voir Autocomplétion Typst.
• Tapez / au début d’une ligne, ou après une espace, pour des extraits : titres, figures, tableaux, équations, notes de bas de page, un sommaire, une bibliographie, et plus.
• ⌘/ / Ctrl+/ commente ou décommente les lignes sélectionnées avec //.

Aperçu des maths

Avec le curseur à l’intérieur d’une équation, Typst dessine le résultat juste au-dessus. Le menu de l’aperçu peut le masquer jusqu’à ce que vous quittiez l’équation, ou le désactiver.

Collez des maths LaTeX comme $\frac{a}{b}$ dans un fichier Typst et un bouton Coller en maths Typst apparaît dessous. Cliquez dessus pour remplacer ce que vous avez collé par des maths Typst, ou appuyez sur Esc pour garder le LaTeX. Pour des maths LaTeX déjà présentes dans le fichier, sélectionnez-les et choisissez Convertir les maths LaTeX en Typst dans le menu contextuel. Pour des conversions ponctuelles, l’outil Équation vers Typst fait la même chose en dehors d’un projet.

Ajouter une figure avec légende

1. Choisissez Insérer une figure dans la barre d’outils.
2. Choisissez plot.png sous Images du projet, ou choisissez Importer depuis le disque… pour le copier dans le projet.
3. Choisissez Trois quarts de largeur, puis activez Ajouter une légende et Ajouter une étiquette. Saisissez la légende et l’étiquette fig:measurements.
4. Ajoutez un Texte alternatif qui décrit l’image pour les lecteurs d’écran, et choisissez un Placement si la figure doit flotter en haut ou en bas de la page.
5. Choisissez Insérer la figure.

Oleafly écrit une figure comme celle-ci :

#figure(
  image("figures/plot.png", width: 75%),
  caption: [Measurements across three runs.],
) <fig:measurements>

See @fig:measurements for the comparison.

Pour modifier la figure plus tard, placez le curseur à l’intérieur et choisissez à nouveau Insérer une figure. La boîte de dialogue s’ouvre alors sous le titre Modifier la figure, avec les valeurs actuelles.

Tableaux depuis des fichiers de données

Faites un clic droit dans l’éditeur et choisissez Tableau depuis un CSV/XLSX…. Choisissez un fichier CSV, TSV, Excel ou JSON, vérifiez l’aperçu, puis ajoutez une légende et une étiquette si vous les voulez. Insérer au curseur écrit un tableau Typst avec les mêmes filets que le tableau de la barre d’outils. Le texte de cellule que Typst lirait comme du balisage est échappé.

Activez Garder le lien avec le fichier de données pour que le tableau reste lié à ses données. Oleafly copie les données dans le dossier data du projet, et le tableau lit ce fichier à chaque compilation du document. Modifiez le fichier et le tableau change à la compilation suivante. Importer un tableau depuis un fichier de données couvre la boîte de dialogue en détail.

Ajouter des citations

Citez avec Citer depuis le projet, ou tapez @ et choisissez une clé dans la liste d’autocomplétion. Une clé de citation et une étiquette de document utilisent toutes deux @ en Typst ; c’est la bibliographie ou l’étiquette qui fournit la cible.

Placez la bibliographie à l’endroit où la liste des références doit apparaître :

#bibliography("references.bib")

Le fichier peut être en BibTeX (.bib) ou Hayagriva (.yml), et l’appel peut nommer une liste de fichiers. Une citation ajoutée depuis Références et citations va dans le fichier que le document déclare, convertie en Hayagriva quand ce fichier l’exige. Pour changer le style des références, utilisez le menu Style de citation en bas du panneau Références, qui écrit l’argument style: pour vous. Voir Choisir un style de citation Typst.

Paquets, réglages et analyse

Trois boutons à l’extrémité droite de la barre d’outils agissent sur tout le document :

• Paquets Typst cherche dans Typst Universe et écrit la ligne #import. Quand un import nomme une version antérieure, l’éditeur propose de le mettre à jour. Un projet peut aussi conserver ses propres copies de ses paquets pour compiler hors ligne. Voir Paquets et Paquets de Typst Universe.
• Analyse du document liste les titres, figures, tableaux, équations, étiquettes, citations et tâches à faire, et copie le titre, les auteurs, les mots-clés et le résumé pour un formulaire de soumission. Typst lit le document à l’ouverture de la boîte de dialogue, donc les numéros et les pages sont à jour. Voir Analyse du document.
• Réglages du document change la taille de page, les marges, les colonnes, la police du corps, la taille, la langue, la justification, l’interligne et la numérotation des titres et des équations. Oleafly écrit vos choix dans les règles #set du fichier principal. Il abrite aussi les variantes de compilation du projet. Voir Réglages du document.

Erreurs et vérifications

Quand une compilation échoue, chaque erreur est soulignée dans son fichier, sur la plage exacte que Typst signale. Survolez le soulignement pour lire le message et les indices de Typst. Les erreurs courantes, comme un nom inconnu, un fichier ou un paquet manquant, ou un crochet non fermé, sont accompagnées d’une explication simple. Voir Erreurs de compilation dans la source.

Orthographe et grammaire vérifie le texte des fichiers Typst, y compris les légendes, les cellules de tableau et les champs de modèle comme abstract:, et ignore le code. Prévérification vérifie dans les sources Typst les références et citations non résolues, le texte alternatif manquant, les images manquantes, les métadonnées du document et les problèmes de revue en aveugle.

Sauter entre le source et le PDF

Choisissez Aller au PDF dans la barre d’outils ou appuyez sur ⌘⇧J / Ctrl+Shift+J pour aller du curseur à la page. Dans le PDF, maintenez ⌘ ou Ctrl et cliquez sur un mot pour revenir à sa ligne, même dans un fichier intégré avec #include. La synchronisation exige Typst 0.13 ou une version ultérieure. Voir Synchronisation source et PDF.

Formater le fichier

Formater le document nettoie tout le fichier avec typstyle. Appuyez sur ⇧⌥F / Shift+Alt+F ou choisissez-le dans le menu contextuel. Formater la sélection formate seulement les lignes sélectionnées. Pour formater à chaque appui sur ⌘S / Ctrl+S, activez Formater à l’enregistrement sous Typst dans Paramètres → Apparence → Éditeur. Voir Formater un fichier Typst.

Versions de Typst

Oleafly est fourni avec Typst 0.15.1, et Paramètres → Moteurs → Typst liste Typst 0.11 à 0.15 au téléchargement. Un nouveau projet épingle la version par défaut, pour que ses coupures de ligne et son nombre de pages restent les mêmes quand Oleafly livrera plus tard un Typst plus récent. Pour changer la version d’un projet, ouvrez la flèche à côté de Recompiler et choisissez sous Version de Typst (ce projet). Le serveur de langage suit la version du projet. Versions de Typst explique les épinglages, les versions manquantes et comment tester une version plus récente avant de basculer.

Organiser et exporter

Découpez un long rapport en fichiers et incluez-les avec #include "sections/method.typ". Gardez les figures, les données, les polices et les fichiers de bibliographie dans le projet, pour qu’un ZIP du source emporte tout ce dont le document a besoin.

Compilez pour vérifier le résultat, puis ouvrez Exporter. Il propose Exporter en PDF, Exporter le source (.zip), Exporter la page en PNG et Images et HTML, qui écrit des pages PNG ou SVG ou un fichier HTML avec Typst lui-même. À partir de Typst 0.13, les exports Word, HTML, Markdown, LaTeX et texte brut passent par la sortie HTML de Typst elle-même, si bien que les équations et les références survivent. Voir Exporter et convertir un projet. Compiler explique les journaux et les options de compilation, et fichiers et dossiers couvre l’organisation du projet.

Pour déplacer un projet LaTeX existant vers Typst, voir Convertir un projet LaTeX en Typst.