# Opciones

Todos los puntos de entrada (`codeToHtml`, `codeToTokens`, `codeToTokensResult`,
`codeToHast`) aceptan el mismo arreglo de opciones como segundo argumento. Solo `lang`
y un tema son obligatorios.

## `lang`

**Obligatorio.** El identificador o alias del idioma que se usará para tokenizar: `php`, `ts`, `js`,
`rust`, `python`, `html`, etc. El valor especial `'ansi'` resalta las secuencias de escape del terminal en lugar de usar una gramática (consulta [ANSI](https://shikiphp.inline0.dev/es/docs/ansi)).

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

## `theme`

Un único identificador de tema. Es obligatorio salvo que se indique `themes`.

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

## `themes`

Un mapa de claves a identificadores de temas para generar temas dobles (o múltiples) mediante variables CSS. Es obligatorio salvo que se indique `theme`.

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

## `defaultColor`

Qué clave de `themes` se convierte en el color predeterminado en línea (las demás pasan a ser variables `--shiki-<key>` CSS). El valor predeterminado es `'light'`. Indique `false` para emitir solo variables, sin un valor predeterminado en línea; resulta práctico cuando controla todos los colores desde CSS.

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

## `transformers`

Una lista de objetos `Shikiphp\Transformer\Transformer` que se aplican a través del flujo. Consulte [Transformadores](https://shikiphp.inline0.dev/es/docs/transformers).

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

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

## `decorations`

Aplique clases o atributos a rangos arbitrarios del código fuente según la línea y la posición del carácter. Cada decoración es `{start, end, properties}`, donde las posiciones son `{line, character}` (desde cero).

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

## `colorReplacements`

Remapea los colores de la salida. Las entradas de tipo cadena reemplazan un color globalmente; las entradas anidadas, identificadas por nombre de tema, solo se aplican a ese tema.

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

## `structure`

`'classic'` (predeterminado) emite la estructura completa de `pre > code > span.line > span`.
`'inline'` emite solo los tramos de tokens con saltos de línea, sin envolverlos en `pre`/`code`; resulta útil para fragmentos en línea.

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

## `tabindex`

El atributo `tabindex` del elemento `<pre>`. El valor predeterminado es `0`. Pase `false` para omitirlo.

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

## `cssVariablePrefix`

El prefijo que se usa para las variables CSS de temas dobles. El valor predeterminado es `'--shiki-'`.

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

## `mergeWhitespaces`

Controla cómo se gestionan los tokens de espacios en blanco. `true` (predeterminado) incorpora los tokens que solo contienen espacios en blanco al siguiente token; `'never'` separa los espacios en blanco iniciales y finales de cada token en tokens independientes; `false` deja los tokens sin cambios.

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

## `tokenizeMaxLineLength`

Omite la tokenización y emite un único token de texto sin formato para cualquier línea que alcance o supere esta longitud, en unidades de código UTF-16. Sin límite de forma predeterminada. Protege frente a entradas patológicas de una sola línea.

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

## `meta`

Metadatos arbitrarios que se pasan a los transformadores a través del contexto del transformador; por ejemplo, la cadena de metadatos de un bloque de código consumida por
[`MetaHighlight`](https://shikiphp.inline0.dev/es/docs/transformers#metahighlight) y
[`MetaWordHighlight`](https://shikiphp.inline0.dev/es/docs/transformers#metawordhighlight).

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

## `grammarState`

Un `Shikiphp\GrammarState` (de `getLastGrammarState`) desde el que reanudar la tokenización.
Los valores `lang` y theme(s) conservados deben coincidir. Consulte
[`getLastGrammarState`](https://shikiphp.inline0.dev/es/docs/api#shikiphpgetlastgrammarstate).