AnisAbdellatif/typst

Que fait typst ?

Typst est un système de composition typographique basé sur le balisage, doté d'un langage de script intégré. Un seul binaire compile .typ → PDF (par défaut), PNG, SVG, HTML (expérimental) ou un bundle multi-fichiers (expérimental). Cette compétence cible Typst 0.15.x (vérifié sur 0.15.1) ; des notes signalent les comportements qui diffèrent dans les versions plus anciennes.

Les données d'apprentissage sur Typst sont souvent obsolètes (ère 0.11–0.13). En cas de doute sur une fonction, un paramètre ou une valeur par défaut, vérifiez references/api-signatures.md, puis compilez une sonde (typst eval '<expr>' ou un fichier de 5 lignes) plutôt que de deviner.

Workflow

1. Clarifiez la sortie : PDF (défaut), HTML, PNG/SVG, PDF accessible (PDF/UA), PDF d'archivage (PDF/A) ? Taille de page, langue, polices, style de citation, modèle/journal ?
2. Partez d'un squelette (ci-dessous) ou de exemples/. Pour un journal/thèse/CV/diaporama, cherchez d'abord un paquet : python3 scripts/search-packages.py "ieee paper" (voir references/packages-and-ecosystem.md).
3. Écrivez le fichier : placez les règles set/show et les imports en haut, le contenu en dessous. Divisez les grands projets avec #include et #import.
4. Compilez et vérifiez : typst compile main.typ — lisez les diagnostics (ils contiennent ligne:col et des indices). Vérifiez visuellement via PNG (typst compile main.typ 'p-{p}.png') ou textuellement via typst compile main.typ - -f html --features html / pdftotext. Détails dans references/pitfalls-and-debugging.md.
5. Formatez (si disponible) : typstyle -i file.typ. Uniquement lorsque la différence se limite à vos propres modifications.
6. Signalez quels fichiers ont été créés/modifiés et comment reconstruire.

Squelette minimal

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

#title()

= Introduction <intro>
Typst supporte *gras*, _italique_, `raw`, les maths $E = m c^2$ et les références comme @intro.

== Une sous-section
#lorem(30)

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

Valeurs par défaut toujours sûres : #set text(lang: "...") (césure, guillemets, suppléments, accessibilité), #set document(title: ...) + #title() pour le titre visible, #set par(justify: true) pour le corps du texte.

Syntaxe en 60 secondes

Mode	Entrée avec	Exemple
Markup (défaut)	—	= Titre, *fort*, _emph_, - élément, + numéroté, / Terme : desc, @label, <label>
Code	# (une expression) ou bloc #{ ... }	#let x = 3, #f(1)[corps], #if a [oui] else [non], #for i in range(3) [#i ]
Maths	$...$ ($ x $ avec espaces = affichage)	$a^2 + b_i$, $sum_(i=1)^n i$, $ vec(1, 2) $
Bloc de contenu	[...] dans le code	#box[hi], let c = [*x*]

• Dans le code, ne répétez pas # : #figure(image("a.png"), caption: [Salut]). À l'intérieur des blocs de contenu [...], vous êtes de retour en markup : [Total : #x].
• Tableaux (1, 2), dictionnaires (a: 1, b: 2), vides () / (:), à un élément (1,). Il n'y a pas de tuples. Indexez avec .at(i), pas [i].
• Les arguments nommés utilisent : (f(largeur: 2cm)); = est une affectation uniquement dans let/code.
• Chaînes "...", contenu [...], brut `...`. Convertissez avec str(x), [#s], eval(s, mode: "markup").
• Commentaires : // ligne, /* bloc */. Échappez les spéciaux avec \ (\#, \$, \@, \*, \_, \<) ; unicode \u{1F600}.
• Unités de longueur : pt mm cm in em, fr (fraction), %, angles deg rad. auto et none sont des valeurs.
• set = arguments par défaut pour un élément à partir d'ici ; show = re-style/remplacer des éléments. context est nécessaire pour lire les styles/compteurs/positions (voir references/introspection.md).
• Chemins : uniquement des barres obliques (0.15). "/x.typ" est relatif à la racine du projet (racine par défaut : dossier du fichier principal ; changez avec --root), "x.typ" est relatif au fichier courant.
• Syntaxe de méthode partout : "abc".len(), (1,2,3).map(x => x*2), rgb("#f00").lighten(30%).

Où chercher

Besoin	Lire
Syntaxe, types, opérateurs, méthodes chaîne/tableau/dict, modules, fermetures, bases de context	references/syntax-and-scripting.md
Règles set/show, sélecteurs, configuration de page, texte, paragraphes, blocs, grilles, colonnes, alignement, espacement, placement, transformations	references/styling-and-layout.md
Titres, listes, figures, tableaux, références, notes de bas de page, tables des matières, citations, bibliographie/CSL, numérotation, liens, métadonnées	references/document-model.md
Équations, syntaxe mathématique, symboles, matrices, alignement, polices, numérotation	references/math.md
Formes, courbes, images, couleurs, dégradés, pavages, traits, couleurs d'accompagnement	references/visuals.md
Compteurs, état, query, locate, metadata, within, convergence de mise en page, en-têtes courants, measure/layout	references/introspection.md
CSV/JSON/YAML/TOML/XML/CBOR, read, bytes, sys.inputs, eval, plugins WASM, documents pilotés par les données	references/data-and-io.md
Options CLI, polices, PDF/A/UA, accessibilité, HTML, bundle, PNG/SVG, typst eval, CI/constructions reproductibles	references/export-and-cli.md
Diaporamas (Touying/Polylux, animations, polycopiés, notes de l'orateur, pdfpc)	references/slides.md
Modèles, typst.toml, publication de paquets, sélection de paquets Universe (cetz, fletcher, touying, codly, ...), outils d'édition	references/templates-and-packages.md, references/packages-and-ecosystem.md
Traduction LaTeX → Typst, conversion Markdown/pandoc, mise à jour depuis 0.11–0.14	references/migration.md
Erreurs, avertissements, sondes, vérification visuelle, performances, pièges courants	references/pitfalls-and-debugging.md
Paramètres/valeurs par défaut exacts de chaque élément (vérifiés sur la source 0.15.1)	references/api-signatures.md
Exemples prêts à compiler	examples/*.typ

Principaux pièges (à lire avant d'écrire)

1. Les règles set/show s'appliquent vers l'avant et uniquement dans leur portée ; placez-les avant le contenu qu'elles doivent affecter. Un set à l'intérieur de [...]/{...} se termine avec le bloc.
2. Lire quoi que ce soit qui dépend de la position/style nécessite context : #context counter(page).get(), #context text.size. Sans cela : "ne peut être utilisé que lorsque le contexte est connu".
3. Les variables capturées par des fermetures sont des copies en lecture seule ; accumulez via fold, des boucles dans un seul bloc de code, state ou counter.
4. # est nécessaire une fois ; #(a + b) pour les expressions avec opérateurs en markup ; #f(x).g fonctionne mais #f (x) (espace) n'appelle pas.
5. Les maths ne sont pas du texte : les mots multi-lettres sont des symboles/variables (alpha, sin) ; écrivez le texte comme "texte" ou upright(...). Les lettres simples sont des variables en italique.
6. Les chaînes ne sont pas du contenu : un corps de titre est du contenu ; utilisez .body, str() ou l'assistant to-string (voir la référence syntaxique) pour obtenir du texte.
7. Polices : seules les polices installées/intégrées/--font-path fonctionnent ; une famille inconnue émet seulement un avertissement et utilise un repli. Listez avec typst fonts. Pour les polices variables, omettez "Variable"/"VF" dans le nom (0.15).
8. Les paquets sont importés avec des versions exactes : #import "@preview/cetz:0.5.3" — cherchez la dernière version sur Typst Universe (scripts/search-packages.py) plutôt que de faire confiance à la mémoire. Les paquets peuvent accuser un retard par rapport à un nouveau compilateur.
9. Suppressions 0.15 : path() → curve(), pattern → tiling, pdf.embed → pdf.attach, *.decode(...) → passer bytes à json(...) etc., typst query → typst eval, pas d'antislash dans les chemins.
10. L'export HTML/bundle est expérimental et nécessite --features html / --features bundle.

Idiomes rapides

// Modèle réutilisable : règle show avec fonction
#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: [Mon article])

// Styliser un niveau de titre
#show heading.where(level: 1): set text(navy)
#show heading.where(level: 1): it => block(above: 1.5em, below: 1em, it)

// Références croisées et figures
#figure(table(columns: 2, [A], [B], [1], [2]), caption: [Données]) <tab:data>
Voir @tab:data.

// Contenu piloté par les données
#for (name, score) in (("Ann", 3), ("Bo", 5)) [- #name: #score]

// Entrée runtime depuis la CLI : typst compile --input mode=draft main.typ
#let draft = sys.inputs.at("mode", default: "final") == "draft"

Aide-mémoire de compilation

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                   # recompile en cas de changement
typst eval 'calc.pow(2, 10)'           # évalue une expression, sortie JSON
typst eval --in main.typ 'query(heading).len()'
typst init @preview/charged-ieee       # nouveau projet à partir d'un modèle
typst fonts --variants                 # polices installées

Exemples (compilent tous sur 0.15.1)

Fichier	Montre
examples/memo.typ	courte note, grille d'en-tête, style simple
examples/report.typ	page de titre, table des matières, en-tête courant, figures/tableaux/notes de bas de page, règles show
examples/academic-paper.typ (+ refs.bib)	équations, environnements de théorème, références croisées, citations
examples/data-report.typ (+ data.csv)	CSV → tableau, colonnes calculées, --input, graphique à barres en formes simples
examples/template.typ + template-usage.typ	fonction de modèle réutilisable + composants
examples/accessible.typ	PDF/A-2a + PDF/UA-1 (--pdf-standard a-2a,ua-1)
examples/dual-target.typ	une source → PDF et HTML (context target(), html.*)
examples/query-export.typ	metadata + export de structure typst eval
examples/slides-plain.typ, examples/letter.typ	diapositives sans paquet et lettre formelle
examples/packages-demo.typ	cetz, fletcher, lilaq, theorion, codly (versions épinglées et vérifiées)

Scripts

• scripts/check-snippets.py FICHIER.md… — compile chaque bloc ```typ (utilisez ```typ-x pour les blocs illustratifs/non compilables). Exécutez-le sur tout Markdown que vous écrivez contenant du Typst.
• scripts/search-packages.py "mots-clés" [--category cv] [--name cetz --versions] — interroge l'index de Typst Universe pour les noms/versions actuels des paquets.