AnisAbdellatif/typst

Was macht typst?

Typst ist ein markup-basiertes Textsatzsystem mit einer integrierten Skriptsprache. Eine einzelne Binärdatei kompiliert .typ → PDF (Standard), PNG, SVG, HTML (experimentell) oder ein Multi-Datei-Bundle (experimentell). Diese Skill zielt auf Typst 0.15.x (gegen 0.15.1 verifiziert); Anmerkungen markieren Verhalten, das in älteren Versionen abweicht.

Trainingsdaten über Typst sind oft veraltet (Ära 0.11–0.13). Bei Unsicherheit über eine Funktion, einen Parameter oder eine Voreinstellung zuerst references/api-signatures.md prüfen, dann einen Test kompilieren (typst eval '<ausdruck>' oder eine 5-zeilige Datei) anstatt zu raten.

Arbeitsablauf

1. Ausgabe klären: PDF (Standard), HTML, PNG/SVG, barrierefreies PDF (PDF/UA), Archiv-PDF (PDF/A)? Papierformat, Sprache, Schriften, Zitierstil, Vorlage/Journal?
2. Von einem Grundgerüst (unten) oder aus examples/ starten. Für ein Journal/eine Thesis/einen Lebenslauf/eine Folienpräsentation zuerst ein Paket suchen: python3 scripts/search-packages.py "ieee paper" (siehe references/packages-and-ecosystem.md).
3. Datei schreiben: set/show-Regeln und Importe an den Anfang setzen, Inhalt darunter. Große Projekte mit #include und #import aufteilen.
4. Kompilieren und prüfen: typst compile main.typ — die Diagnosen lesen (sie haben Zeile:Spalte und Hinweise). Visuell via PNG prüfen (typst compile main.typ 'p-{p}.png'), oder textuell via typst compile main.typ - -f html --features html / pdftotext. Details in references/pitfalls-and-debugging.md.
5. Formatieren (falls verfügbar): typstyle -i file.typ. Nur wenn der Diff auf Ihre eigenen Änderungen beschränkt ist.
6. Berichten, welche Dateien erstellt/geändert wurden und wie neu gebaut wird.

Minimales Grundgerüst

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

#title()

= Einleitung <intro>
Typst unterstützt *fett*, _kursiv_, `wörtlich`, Mathe $E = m c^2$ und Referenzen wie @intro.

== Ein Unterabschnitt
#lorem(30)

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

Immer sichere Voreinstellungen: #set text(lang: "...") (Silbentrennung, Anführungszeichen, Ergänzungen, Barrierefreiheit), #set document(title: ...) + #title() für den sichtbaren Titel, #set par(justify: true) für Fließtext.

Syntax in 60 Sekunden

Modus	Eingabe mit	Beispiel
Markup (Standard)	—	= Überschrift, *fett*, _kursiv_, - Punkt, + nummeriert, / Begriff: Beschreibung, @label, <label>
Code	# (ein Ausdruck) oder #{ ... } Block	#let x = 3, #f(1)[body], #if a [ja] else [nein], #for i in range(3) [#i ]
Mathe	$...$ ($ x $ mit Leerzeichen = Display)	$a^2 + b_i$, $sum_(i=1)^n i$, $ vec(1, 2) $
Inhaltblock	[...] innerhalb von Code	#box[hi], let c = [*x*]

• Innerhalb von Code # nicht wiederholen: #figure(image("a.png"), caption: [Hallo]). Innerhalb von [...]-Inhaltblöcken befinden Sie sich wieder im Markup: [Summe: #x].
• Arrays (1, 2), Dictionaries (a: 1, b: 2), leer () / (:), ein-element (1,). Es gibt keine Tupel. Zugriff mit .at(i), nicht [i].
• Benannte Argumente verwenden : (f(width: 2cm)); = ist nur innerhalb von let/Code eine Zuweisung.
• Zeichenketten "...", Inhalt [...], wörtlich `...`. Umwandeln mit str(x), [#s], eval(s, mode: "markup").
• Kommentare: // Zeile, /* Block */. Sonderzeichen mit \ escapen (\#, \$, \@, \*, \_, \<); Unicode \u{1F600}.
• Längeneinheiten: pt mm cm in em, fr (Bruchteil), %, Winkel deg rad. auto und none sind Werte.
• set = Standardargumente für ein Element ab hier; show = Elemente umstylen/ersetzen. context ist erforderlich, um Stile/Zähler/Positionen zu lesen (siehe references/introspection.md).
• Pfade: nur Vorwärtsschrägstriche (0.15). "/x.typ" ist relativ zum Projektstamm (Standardstamm: Verzeichnis der Hauptdatei; ändern mit --root), "x.typ" ist relativ zur aktuellen Datei.
• Methodensyntax überall: "abc".len(), (1,2,3).map(x => x*2), rgb("#f00").lighten(30%).

Wo nachschlagen

Bedarf	Lesen
Syntax, Typen, Operatoren, Zeichenketten-/Array-/Dict-Methoden, Module, Closures, context-Grundlagen	references/syntax-and-scripting.md
set/show-Regeln, Selektoren, Seiteneinrichtung, Text, Absätze, Blöcke, Raster, Spalten, Ausrichtung, Abstände, Positionierung, Transformationen	references/styling-and-layout.md
Überschriften, Listen, Abbildungen, Tabellen, Referenzen, Fußnoten, Gliederungen, Zitate, Bibliografie/Zitationen/CSL, Nummerierung, Links, Metadaten	references/document-model.md
Gleichungen, Mathe-Syntax, Symbole, Matrizen, Ausrichtung, Schriften, Nummerierung	references/math.md
Formen, Kurven, Bilder, Farben, Verläufe, Kachelungen, Striche, Schmuckfarben	references/visuals.md
Zähler, Zustände, query, locate, metadata, within, Layout-Konvergenz, laufende Kopfzeilen, measure/layout	references/introspection.md
CSV/JSON/YAML/TOML/XML/CBOR, read, bytes, sys.inputs, eval, WASM-Plugins, datengetriebene Dokumente	references/data-and-io.md
CLI-Flags, Schriften, PDF/A/UA, Barrierefreiheit, HTML, Bundle, PNG/SVG, typst eval, CI/reproduzierbare Builds	references/export-and-cli.md
Folienpräsentationen (Touying/Polylux, Animationen, Handouts, Sprechernotizen, pdfpc)	references/slides.md
Vorlagen, typst.toml, Pakete veröffentlichen, Universe-Paketauswahl (cetz, fletcher, touying, codly, ...), Editor-Werkzeuge	references/templates-and-packages.md, references/packages-and-ecosystem.md
LaTeX → Typst-Übersetzung, Markdown/pandoc-Konvertierung, Upgrade von 0.11–0.14	references/migration.md
Fehler, Warnungen, Tests, visuelle Überprüfung, Leistung, häufige Fallstricke	references/pitfalls-and-debugging.md
Genaue Parameter/Voreinstellungen jedes Elements (gegen 0.15.1-Quelle verifiziert)	references/api-signatures.md
Kompilierfertige Startbeispiele	examples/*.typ

Hauptfallstricke (vor dem Schreiben lesen)

1. Set/Show-Regeln wirken vorwärts und nur innerhalb ihres Gültigkeitsbereichs; sie vor den Inhalt setzen, den sie beeinflussen sollen. Ein set innerhalb von [...]/{...} endet mit dem Block.
2. Um etwas zu lesen, das von Position/Style abhängt, wird context benötigt: #context counter(page).get(), #context text.size. Ohne: "kann nur verwendet werden, wenn context bekannt ist".
3. Von Closures eingefangene Variablen sind schreibgeschützte Kopien; akkumulieren via fold, Schleifen in einem Codeblock, state oder counter.
4. # wird einmal benötigt; #(a + b) für Ausdrücke mit Operatoren in Markup; #f(x).g funktioniert, aber #f (x) (Leerzeichen) ruft nicht auf.
5. Mathe ist kein Text: Mehrbuchstabenwörter sind Symbole/Variablen (alpha, sin); Text als "text" oder upright(...) schreiben. Einzelbuchstaben sind kursive Variablen.
6. Zeichenketten sind kein Inhalt: ein Überschriftenkörper ist Inhalt; .body, str() oder den Helfer to-string verwenden (siehe Syntax-Referenz), um Text zu erhalten.
7. Schriften: nur installierte/eingebettete/--font-path-Schriften funktionieren; eine unbekannte Familie warnt nur und fällt zurück. Auflisten mit typst fonts. Bei variablen Schriften "Variable"/"VF" im Namen weglassen (0.15).
8. Pakete werden mit exakten Versionen importiert: #import "@preview/cetz:0.5.3" — die neueste Version im Typst Universe nachschlagen (scripts/search-packages.py) anstatt sich zu erinnern. Pakete können hinter einem neuen Compiler zurückbleiben.
9. Entfernungen in 0.15: path() → curve(), pattern → tiling, pdf.embed → pdf.attach, *.decode(...) → bytes an json(...) usw. übergeben, typst query → typst eval, keine Backslashes in Pfaden.
10. HTML-/Bundle-Export ist experimentell und benötigt --features html / --features bundle.

Kurze Redewendungen

// Wiederverwendbare Vorlage: Show-Regel mit Funktion
#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: [Mein Aufsatz])

// Eine Überschriftenebene stylen
#show heading.where(level: 1): set text(navy)
#show heading.where(level: 1): it => block(above: 1.5em, below: 1em, it)

// Querverweise und Abbildungen
#figure(table(columns: 2, [A], [B], [1], [2]), caption: [Daten]) <tab:data>
Siehe @tab:data.

// Datengetriebener Inhalt
#for (name, score) in (("Ann", 3), ("Bo", 5)) [- #name: #score]

// Laufzeiteingabe von der CLI: typst compile --input mode=draft main.typ
#let draft = sys.inputs.at("mode", default: "final") == "draft"

Kompilier-Spickzettel

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                   # bei Änderung neu kompilieren
typst eval 'calc.pow(2, 10)'           # Ausdruck auswerten, JSON-Ausgabe
typst eval --in main.typ 'query(heading).len()'
typst init @preview/charged-ieee       # neues Projekt von einer Vorlage
typst fonts --variants                 # installierte Schriften

Beispiele (alle kompilieren mit 0.15.1)

Datei	Zeigt
examples/memo.typ	kurzes Memo, Kopfzeilenraster, einfaches Styling
examples/report.typ	Titelseite, Gliederung, laufende Kopfzeile, Abbildungen/Tabellen/Fußnoten, Show-Regeln
examples/academic-paper.typ (+ refs.bib)	Gleichungen, Theoreme, Querverweise, Zitationen
examples/data-report.typ (+ data.csv)	CSV → Tabelle, berechnete Spalten, --input, einfaches Balkendiagramm
examples/template.typ + template-usage.typ	wiederverwendbare Vorlagenfunktion + Komponenten
examples/accessible.typ	PDF/A-2a + PDF/UA-1 (--pdf-standard a-2a,ua-1)
examples/dual-target.typ	eine Quelle → PDF und HTML (context target(), html.*)
examples/query-export.typ	metadata + typst eval Strukturexport
examples/slides-plain.typ, examples/letter.typ	paketfreie Folien und ein formeller Brief
examples/packages-demo.typ	cetz, fletcher, lilaq, theorion, codly (festgelegte, verifizierte Versionen)

Skripte

• scripts/check-snippets.py DATEI.md… — kompiliert jeden ```typ Block (für illustrative/nicht kompilierende Blöcke ```typ-x verwenden). Führen Sie es für jedes Markdown aus, das Sie schreiben und das Typst enthält.
• scripts/search-packages.py "schlüsselwörter" [--category cv] [--name cetz --versions] — den Typst-Universe-Index nach aktuellen Paketnamen/-versionen durchsuchen.