# Optionen

Alle Einstiegspunkte (`codeToHtml`, `codeToTokens`, `codeToTokensResult`,
`codeToHast`) verwenden dasselbe Optionsarray als zweites Argument. Erforderlich sind nur `lang`
und ein Theme.

## `lang`

**Erforderlich.** Die Sprach-ID oder der Alias für die Tokenisierung — `php`, `ts`, `js`,
`rust`, `python`, `html` usw. Der Sonderwert `'ansi'` hebt
Terminal-Escape-Sequenzen statt einer Grammatik hervor (siehe [ANSI](https://shikiphp.inline0.dev/de/docs/ansi)).

```php
['lang' => 'php']
```

## `theme`

Eine einzelne Theme-ID. Erforderlich, sofern `themes` nicht angegeben ist.

```php
['lang' => 'php', 'theme' => 'github-dark']
```

## `themes`

Eine Zuordnung von Schlüsseln zu Theme-IDs für die Ausgabe mit zwei (oder mehreren) Themes über CSS-Variablen.
Erforderlich, sofern `theme` nicht angegeben ist.

```php
['lang' => 'ts', 'themes' => ['light' => 'github-light', 'dark' => 'github-dark']]
```

## `defaultColor`

Welcher Schlüssel in `themes` zur Standardfarbe für Inline-Elemente wird (die anderen werden zu
`--shiki-<key>`-CSS-Variablen). Standardmäßig `'light'`. Setze den Wert auf `false`, um
nur Variablen und keine Inline-Standardfarbe auszugeben — praktisch, wenn du alle Farben über
CSS steuerst.

```php
['themes' => ['light' => '…', 'dark' => '…'], 'defaultColor' => 'dark']
```

## `transformers`

Eine Liste von `Shikiphp\Transformer\Transformer`-Objekten, die über die
Pipeline angewendet werden. Siehe [Transformers](https://shikiphp.inline0.dev/de/docs/transformers).

```php
use Shikiphp\Transformer\Notation\NotationHighlight;

['transformers' => [new NotationHighlight()]]
```

## `decorations`

Wende Klassen oder Attribute anhand der Zeilen- und Zeichenposition auf beliebige Bereiche des Quelltexts an.
Jede Dekoration ist `{start, end, properties}`, wobei die Positionen `{line, character}` sind (nullbasiert).

```php
['decorations' => [
    [
        'start'      => ['line' => 0, 'character' => 0],
        'end'        => ['line' => 0, 'character' => 5],
        'properties' => ['class' => 'highlight'],
    ],
]]
```

## `colorReplacements`

Farben in der Ausgabe neu zuordnen. Einträge als Zeichenfolgen ersetzen eine Farbe global; verschachtelte
Einträge mit Theme-Namen als Schlüssel gelten nur für dieses Theme.

```php
['colorReplacements' => [
    '#ffffff'      => '#f8f8f2',          // global
    'github-dark'  => ['#24292e' => '#000'], // only in github-dark
]]
```

## `structure`

`'classic'` (Standard) gibt die vollständige `pre > code > span.line > span`-Struktur aus.
`'inline'` gibt nur die Token-Spans mit Zeilenumbrüchen aus, ohne umschließende
`pre`/`code` — nützlich für Inline-Codeausschnitte.

```php
['structure' => 'inline']
```

## `tabindex`

Das Attribut `tabindex` des Elements `<pre>`. Standardmäßig `0`. Übergib `false`,
um es wegzulassen.

```php
['tabindex' => false]
```

## `cssVariablePrefix`

Das Präfix für die CSS-Variablen mit mehreren Themes. Standardmäßig `'--shiki-'`.

```php
['cssVariablePrefix' => '--my-']
```

## `mergeWhitespaces`

Steuert den Umgang mit Leerraum-Token. `true` (Standard) fasst reine Leerraum-Token mit dem folgenden Token zusammen; `'never'` zerlegt den führenden und
nachgestellten Leerraum jedes Tokens in eigenständige Token; `false` lässt die Token unverändert.

```php
['mergeWhitespaces' => 'never']
```

## `tokenizeMaxLineLength`

Überspringe die Tokenisierung für jede Zeile, die mindestens diese Länge hat, und gib dafür ein einzelnes Plain-Token aus; Längenangabe in UTF-16-Codeeinheiten. Standardmäßig gibt es kein Limit. Schützt vor problematisch langen einzeiligen Eingaben.

```php
['tokenizeMaxLineLength' => 1000]
```

## `meta`

Beliebige Metadaten, die über den Transformer-Kontext an Transformers weitergegeben werden —
zum Beispiel die Meta-Zeichenfolge eines Codeblocks, die von
[`MetaHighlight`](https://shikiphp.inline0.dev/de/docs/transformers#metahighlight) und
[`MetaWordHighlight`](https://shikiphp.inline0.dev/de/docs/transformers#metawordhighlight) verarbeitet wird.

```php
['meta' => ['__raw' => '{1,3-5}']]
```

## `grammarState`

Ein `Shikiphp\GrammarState` (aus `getLastGrammarState`), ab dem die Tokenisierung fortgesetzt wird.
Die übernommenen Werte `lang` und theme(s) müssen übereinstimmen. Siehe
[`getLastGrammarState`](https://shikiphp.inline0.dev/de/docs/api#shikiphpgetlastgrammarstate).