문서
가이드
구문 강조

구문 강조

Nextra는 빌드 시 구문 강조를 위해 Shiki (opens in a new tab)를 사용합니다. 매우 신뢰할 수 있고 성능이 좋습니다. 예를 들어, Markdown 파일에 다음과 같이 추가하면:

Markdown
```js
console.log("hello, world");
```

결과는 다음과 같습니다:

console.log("hello, world");

기능

인라인 코드

let x = 1 같은 인라인 구문 강조도 {:} 구문을 통해 지원됩니다:

Markdown
인라인 구문 강조도 지원됩니다 `let x = 1{:jsx}` 다음을 통해:

라인 강조

코드 블록에 {} 속성을 추가하여 특정 라인을 강조할 수 있습니다:

Markdown
```js {1,4-5}
import { useState } from "react";
 
function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
}
```

결과:

import { useState } from "react";
 
function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
}

부분 문자열 강조

코드 블록에 // 속성을 추가하여 특정 부분 문자열을 강조할 수 있습니다:

Markdown
```js /useState/
import { useState } from "react";
 
function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
}
```
import { useState } from "react";
 
function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
}

숫자를 추가하여 해당 부분 문자열의 특정 발생만 강조할 수 있습니다: /str/1, 또는 여러 개: /str/1-3, /str/1,3.

복사 버튼

copy 속성을 추가하면 사용자가 코드 블록 위에 마우스를 올렸을 때 복사 버튼이 나타납니다:

Markdown
```js copy
console.log("hello, world");
```

렌더링:

console.log("hello, world");

Nextra 구성(next.config.js 파일)에서 defaultShowCopyCode: true를 설정하여 이 기능을 전역적으로 활성화할 수 있습니다. 전역적으로 활성화되면 copy=false 속성을 통해 비활성화할 수 있습니다.

라인 번호

showLineNumbers 속성을 추가하여 코드 블록에 라인 번호를 추가할 수 있습니다:

Markdown
```js showLineNumbers
import { useState } from "react";
 
function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
}
```

렌더링:

import { useState } from "react";
 
function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
}

파일명과 제목

filename 속성을 추가하여 코드 블록에 파일명이나 제목을 추가할 수 있습니다:

Markdown
```js filename="example.js"
console.log("hello, world");
```

렌더링:

example.js
console.log("hello, world");

ANSI 강조

ANSI 이스케이프 코드를 강조할 수 있습니다:

Markdown
```ansi
 ✓ src/index.test.ts (1)
   Test Files  1 passed (1)
        Tests  1 passed (1)
     Start at  23:32:41
     Duration  11ms
   PASS  Waiting for file changes...
         press h to show help, press q to quit
```

Renders:

 ✓ src/index.test.ts (1)
   Test Files  1 passed (1)
        Tests  1 passed (1)
     Start at  23:32:41
     Duration  11ms
   PASS  Waiting for file changes...
         press h to show help, press q to quit

지원되는 언어

지원되는 모든 언어는 이 목록 (opens in a new tab)에서 확인할 수 있습니다.

테마 커스터마이즈

Nextra는 토큰의 색상을 정의하기 위해 CSS 변수를 사용합니다. 전역 CSS (opens in a new tab)를 주입하여 라이트/다크 테마에서 이를 커스터마이즈할 수 있습니다. 예를 들어 이것이 기본 토큰이며 이 중 어느 것이든 재정의할 수 있습니다:

styles.css
:root {
  --shiki-color-text: #414141;
  --shiki-color-background: transparent;
  --shiki-token-constant: #1976d2;
  --shiki-token-string: #22863a;
  --shiki-token-comment: #aaa;
  --shiki-token-keyword: #d32f2f;
  --shiki-token-parameter: #ff9800;
  --shiki-token-function: #6f42c1;
  --shiki-token-string-expression: #22863a;
  --shiki-token-punctuation: #212121;
  --shiki-token-link: #22863a;
}
 
.dark {
  --shiki-color-text: #d1d1d1;
  --shiki-token-constant: #79b8ff;
  --shiki-token-string: #ffab70;
  --shiki-token-comment: #6b737c;
  --shiki-token-keyword: #f97583;
  --shiki-token-parameter: #ff9800;
  --shiki-token-function: #b392f0;
  --shiki-token-string-expression: #4bb74a;
  --shiki-token-punctuation: #bbb;
  --shiki-token-link: #ffab70;
}

동적 콘텐츠와 함께 사용

구문 강조는 빌드 시에 이루어지므로 코드 블록에 동적 콘텐츠를 사용할 수 없습니다. 그러나 MDX가 매우 강력하기 때문에 클라이언트 JS를 통한 해결 방법이 있습니다. 예를 들어:

dynamic_code.js
function hello () {
  const x = 2 + 3
  console.log(1)
}
Increase the numberChange to `1 + 1`

이 해결 방법은 업데이트된 콘텐츠가 다시 강조 표시되지 않는다는 제한이 있습니다. 예를 들어 숫자를 1 + 1로 업데이트하면 잘못 강조 표시됩니다.

작동 방식을 확인하려면 코드 (opens in a new tab)를 참조하세요.

구문 강조 비활성화

자체 구문 강조 기능을 사용하려면 Nextra의 기본 구문 강조 기능을 비활성화할 수 있습니다. Nextra 구성(next.config.js 파일)에서 codeHighlight: false를 설정하여 전역적으로 구문 강조를 비활성화할 수 있습니다.

OptionTypeDescription
codeHighlightbooleanEnable or disable syntax highlighting. Defaults to `true`.

사용자 정의 문법

Shiki는 사용자 정의 언어 문법으로 구문 강조를 위해 VSCode TextMate 문법 (opens in a new tab)을 사용합니다.

next.config.js 내부의 Nextra 구성에서 mdxOptions.rehypePrettyCodeOptions 옵션의 getHighlighter 함수를 재정의하여 이러한 문법을 제공할 수 있습니다:

next.config.js
import { BUNDLED_LANGUAGES } from "shiki";
 
nextra({
  // ... 다른 옵션들
  mdxOptions: {
    rehypePrettyCodeOptions: {
      getHighlighter: (options) =>
        getHighlighter({
          ...options,
          langs: [
            ...BUNDLED_LANGUAGES,
            // 사용자 정의 문법 옵션, 이러한 옵션을 제공하는 방법은 Shiki 문서를 참조하세요
            {
              id: "my-lang",
              scopeName: "source.my-lang",
              aliases: ["mylang"], // id와 함께 aliases는 마크다운을 작성할 때 사용할 수 있는 허용된 이름에 포함됩니다.
              path: "../../public/syntax/grammar.tmLanguage.json",
            },
          ],
        }),
    },
  },
});

사용자 정의 테마

mdxOptions.rehypePrettyCodeOptions 내에서 CSS 변수에 의존하는 대신 사용자 정의 테마를 제공할 수도 있습니다:

next.config.js
nextra({
  // ... 다른 옵션들
  mdxOptions: {
    rehypePrettyCodeOptions: {
      // VSCode 테마 또는 내장 Shiki 테마, 자세한 정보는 Shiki 문서를 참조하세요
      theme: JSON.parse(
        readFileSync("./public/syntax/arctis_light.json", "utf8")
      ),
    },
  },
});

다중 테마

Nextra는 현재 여러 테마를 지정하는 것을 지원하지 않습니다. Shiki는 모든 테마에 대해 여러 코드 블록을 렌더링하고 data-theme="dark"와 같은 속성으로 태그를 지정하기 때문입니다.

그러나 미래에는 다중 테마가 지원될 예정입니다. shikiji(Shiki의 새로운 포크)에서 진행 상황을 추적할 수 있습니다 https://github.com/antfu/shikiji#multiple-themes (opens in a new tab) 이미 여러 코드 블록을 렌더링하지 않고도 다중 테마를 지원합니다.

마크다운Next.js 링크