# 옵션

모든 진입점(`codeToHtml`, `codeToTokens`, `codeToTokensResult`, `codeToHast`)은 두 번째 인수로 동일한 옵션 배열을 받습니다. `lang`와 테마만 필수입니다.

## `lang`

**필수.** 토큰화에 사용할 언어 ID 또는 별칭입니다. `php`, `ts`, `js`, `rust`, `python`, `html` 등이 있습니다. 특수 값 `'ansi'`은 문법 대신 터미널 이스케이프 시퀀스를 강조 표시합니다([ANSI](https://shikiphp.inline0.dev/ko/docs/ansi) 참조).

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

## `theme`

테마 ID 하나입니다. `themes`을 지정하지 않으면 필수입니다.

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

## `themes`

CSS 변수를 통해 듀얼(또는 다중) 테마 출력을 위한 테마 ID 키 맵입니다. `theme`을 지정하지 않으면 필수입니다.

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

## `defaultColor`

`themes`에서 어떤 키를 인라인 기본 색상으로 사용할지 지정합니다(나머지는 `--shiki-<key>` CSS 변수가 됩니다). 기본값은 `'light'`입니다. `false`로 설정하면 인라인 기본값 없이 변수만 출력합니다. 모든 색상을 CSS에서 제어할 때 유용합니다.

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

## `transformers`

파이프라인을 통해 적용되는 `Shikiphp\Transformer\Transformer` 객체 목록입니다. [트랜스포머](https://shikiphp.inline0.dev/ko/docs/transformers)를 참조하세요.

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

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

## `decorations`

줄/문자 위치를 기준으로 소스의 임의 범위에 클래스나 속성을 적용합니다. 각 데코레이션은 `{start, end, properties}`이며 위치는 `{line, character}`(0부터 시작)입니다.

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

## `colorReplacements`

출력의 색상을 다시 매핑합니다. 문자열 항목은 전체 색상을 대체하고, 테마 이름을 키로 하는 중첩 항목은 해당 테마에만 적용됩니다.

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

## `structure`

`'classic'`(기본값)은 전체 `pre > code > span.line > span` 구조를 출력합니다.
`'inline'`는 줄바꿈이 포함된 토큰 범위만 출력하며, 감싸는 `pre`/`code`는 생략합니다. 인라인 코드 조각에 유용합니다.

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

## `tabindex`

`<pre>` 요소의 `tabindex` 속성입니다. 기본값은 `0`입니다. `false`을 전달하면 생략합니다.

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

## `cssVariablePrefix`

듀얼 테마 CSS 변수에 사용하는 접두사입니다. 기본값은 `'--shiki-'`입니다.

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

## `mergeWhitespaces`

공백 토큰 처리를 제어합니다. `true`(기본값)은 공백만 있는 토큰을 다음 토큰에 합칩니다. `'never'`은 각 토큰의 앞뒤 공백을 독립 토큰으로 분리합니다. `false`는 토큰을 그대로 둡니다.

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

## `tokenizeMaxLineLength`

이 길이 이상인 줄은 토큰화를 건너뛰고 일반 토큰 하나로 출력합니다. 길이는 UTF-16 코드 단위 기준입니다. 기본값은 제한 없음입니다. 비정상적으로 긴 단일 줄 입력을 방지하는 보호 장치입니다.

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

## `meta`

트랜스포머 컨텍스트를 통해 트랜스포머에 전달되는 임의의 메타데이터입니다. 예를 들어 [`MetaHighlight`](https://shikiphp.inline0.dev/ko/docs/transformers#metahighlight) 및 [`MetaWordHighlight`](https://shikiphp.inline0.dev/ko/docs/transformers#metawordhighlight)에서 사용하는 코드 펜스 메타 문자열이 있습니다.

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

## `grammarState`

토큰화를 재개할 기준이 되는 `Shikiphp\GrammarState`(`getLastGrammarState`에서 가져옴)입니다. 전달된 `lang`와 theme(s)는 일치해야 합니다. [`getLastGrammarState`](https://shikiphp.inline0.dev/ko/docs/api#shikiphpgetlastgrammarstate)을 참조하세요.