구문 강조

Astro는 기본적으로 Shiki 및 Prism을 지원합니다. 이를 통해 구문 강조 표시를 제공합니다:

• Markdown 또는 MDX 파일에서 사용되는 모든 코드 펜스 (```).
• .astro 파일의 내장 <Code /> 컴포넌트 (Shiki 제공) 내 콘텐츠.
• .astro 파일의 <Prism /> 컴포넌트 (Prism 제공) 내 콘텐츠.

Expressive Code와 같은 커뮤니티 통합을 추가하면 코드 블록에서 더 많은 텍스트 표시 및 주석 옵션을 사용할 수 있습니다.

Markdown 코드 블록

Markdown 코드 블록은 시작과 끝에 백틱 세 개 (```)가 있는 블록으로 표시됩니다. 시작 백틱 뒤에 사용 중인 프로그래밍 언어를 표시하면 코드의 색상과 스타일을 지정하여 읽기 쉽게 만들 수 있습니다.

```js
// 구문 강조를 사용하는 Javascript 코드
var fun = function lang(l) {
  dateformat.i18n = require('./lang/' + l);
  return true;
};
```

Astro의 Markdown 코드 블록은 기본적으로 Shiki에 의해 스타일이 지정되며, github-dark 테마로 미리 구성됩니다. 컴파일된 출력은 불필요한 CSS 클래스, 스타일시트 또는 클라이언트 측 JS가 없는 인라인 스타일로 제한됩니다.

Prism 스타일시트를 추가하여 Prism의 강조 표시로 전환하거나, markdown.syntaxHighlight 구성 옵션을 사용하여 Astro의 구문 강조 표시를 완전히 비활성화할 수 있습니다.

Shiki와 함께 사용할 수 있는 Markdown 구문 강조 옵션의 전체 목록은 markdown.shikiConfig 참조를 확인하세요.

Shiki의 기본 테마 설정

Astro 구성에서 Markdown 코드 블록에 대한 기본 Shiki 테마를 구성할 수 있습니다:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    shikiConfig: {
      theme: 'dracula',
    },
  },
});

Markdown 코드 블록 옵션의 전체 목록은 Shiki 구성 참조를 확인하세요.

라이트 및 다크 모드 테마 설정

Astro 구성에서 라이트 및 다크 모드를 위한 두 개의 Shiki 테마를 지정할 수 있습니다:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    shikiConfig: {
      themes: {
        light: 'github-light',
        dark: 'github-dark',
      },
    },
  },
});

그런 다음 미디어 쿼리 또는 클래스를 통해 Shiki의 다크 모드 CSS 변수를 추가하여 모든 Markdown 코드 블록에 기본값으로 적용합니다. Shiki 문서 예시의 .shiki 클래스를 .astro-code로 바꿉니다:

src/styles/global.css

@media (prefers-color-scheme: dark) {
  .shiki,
  .shiki span {
  .astro-code,
  .astro-code span {
    color: var(--shiki-dark) !important;
    background-color: var(--shiki-dark-bg) !important;
    /* 선택적으로, 글꼴 스타일을 원하면 사용하세요. */
    font-style: var(--shiki-dark-font-style) !important;
    font-weight: var(--shiki-dark-font-weight) !important;
    text-decoration: var(--shiki-dark-text-decoration) !important;
  }
}

Markdown 코드 블록 옵션의 전체 목록은 Shiki 구성 참조를 확인하세요.

나만의 Shiki 테마 추가

Shiki의 사전 정의된 테마 중 하나를 사용하는 대신 로컬 파일에서 사용자 정의 Shiki 테마를 가져올 수 있습니다.

astro.config.mjs

import { defineConfig } from 'astro/config';
import customTheme from './my-shiki-theme.json';

export default defineConfig({
  markdown: {
    shikiConfig: {
      theme: customTheme,
    },
  },
});

Shiki 테마 사용자 정의

Shiki의 테마 문서에서 테마, 라이트 vs 다크 모드 토글 또는 CSS 변수를 통한 스타일링에 대한 더 많은 사용자 정의 옵션을 확인할 수 있습니다.

다음과 같이 대체하여 Astro 프로젝트에 대한 Shiki 문서의 예시를 조정해야 합니다.

• 코드 블록은 .shiki 대신 .astro-code 클래스를 사용하여 스타일이 지정됩니다.
• css-variables 테마를 사용할 때, 사용자 정의 속성에 --shiki- 대신 --astro-code- 접두사가 붙습니다.

코드 블록 컴포넌트

코드 블록을 렌더링하기 위해 .astro 및 .mdx 파일에서 사용할 수 있는 두 가지 Astro 컴포넌트가 있습니다: <Code /> 및 <Prism />.

이러한 컴포넌트의 Props는 ComponentProps 타입 유틸리티를 사용하여 참조할 수 있습니다.

<Code />

이 컴포넌트는 내부적으로 Shiki에 의해 구동됩니다. 인기 있는 모든 Shiki 테마와 언어뿐만 아니라 사용자 지정 테마, 언어, 트랜스포머, 기본 색상 등 여러 다양한 Shiki 옵션을 지원합니다.

이러한 값은 각각 theme, lang, embeddedLangs, transformers, defaultColor 속성을 사용하여 <Code /> 컴포넌트에 props로 전달됩니다. <Code /> 컴포넌트는 Markdown 코드 블록에 대한 shikiConfig 설정을 상속하지 않습니다.

---
import { Code } from 'astro:components';
---
<!-- 일부 JavaScript 코드에 구문 강조 표시. -->
<Code code={`const foo = 'bar';`} lang="js" />
<!-- 선택 사항: 테마 사용자 정의. -->
<Code code={`const foo = 'bar';`} lang="js" theme="dark-plus" />
<!-- 선택 사항: 줄바꿈 활성화. -->
<Code code={`const foo = 'bar';`} lang="js" wrap />
<!-- 선택 사항: 인라인 코드 출력. -->
<p>
  <Code code={`const foo = 'bar';`} lang="js" inline />
  will be rendered inline.
</p>
<!-- 선택 사항: defaultColor (기본 색상) -->
<Code code={`const foo = 'bar';`} lang="js" defaultColor={false} />

embeddedLangs

타입: string[] | undefined

추가된 버전: astro@6.0.0 새로운 기능

Shiki에서 구문 강조를 위해 포함할 추가 언어입니다.

lang 값은 기본적으로 일부 추가 언어에 대한 강조 표시 지원을 포함할 수 있습니다 (예: lang="svelte"는 ts에 대한 강조 표시도 제공함).

embeddedLangs를 사용하여 추가적이고 표준이 아닌 언어 조합 (예: lang="vue"일 때 jsx 지원)에 대한 지원을 포함하세요.

src/pages/index.astro

---
import { Code } from 'astro:components'

const code = `<script setup lang="tsx">
const Text = ({ text }: { text: string }) => <div>{text}</div>;
</script>

<template>
  <Text text="Hello world" />
</template>
`
---
<Code
  lang="vue"
  embeddedLangs={["tsx"]}
  code={code}
/>

transformers

타입: ShikiTransformer[] | undefined

추가된 버전: astro@4.11.0

code에 적용될 Shiki 트랜스포머의 배열입니다. Astro v4.14.0부터는 트랜스포머에 옵션을 전달하기 위해 Shiki의 meta 속성에 문자열을 제공할 수도 있습니다.

transformers는 클래스만 적용하므로 코드 블록의 요소를 타겟팅하려면 고유한 CSS 규칙을 제공해야 합니다.

src/pages/index.astro

---
import { transformerNotationFocus, transformerMetaHighlight } from '@shikijs/transformers'
import { Code } from 'astro:components'
const code = `const foo = 'hello'
const bar = ' world'
console.log(foo + bar) // [!code focus]
`
---
<Code
  code={code}
  lang="js"
  transformers={[transformerMetaHighlight()]}
  meta="{1,3}"
/>

<style is:global>
  pre.has-focused .line:not(.focused) {
    filter: blur(1px);
  }
</style>

<Prism />

이 컴포넌트는 Prism의 CSS 클래스를 적용하여 코드 블록에 언어별 구문 강조 표시를 제공합니다. 클래스의 스타일을 지정하려면 Prism CSS 스타일시트를 제공 (또는 직접 가져오기)해야 합니다.

Prism 구문 강조 컴포넌트를 사용하려면 @astrojs/prism 패키지를 설치해야 합니다:

npm

npm install @astrojs/prism

pnpm

pnpm add @astrojs/prism

Yarn

yarn add @astrojs/prism

그런 다음 언어와 렌더링할 코드를 전달하여 다른 Astro 컴포넌트와 마찬가지로 <Prism /> 컴포넌트를 가져와 사용할 수 있습니다.

---
import { Prism } from '@astrojs/prism';
---
<Prism lang="js" code={`const foo = 'bar';`} />

Prism에서 지원하는 언어 목록 외에도 lang="astro"를 사용하여 Astro 코드 블록을 표시할 수도 있습니다.

Prism 스타일시트 추가

Prism을 사용하기로 했다면 (markdown.syntaxHighlight: 'prism'을 구성하거나 <Prism /> 컴포넌트를 사용하여) Astro는 코드에 Shiki 대신 Prism의 CSS 클래스를 적용합니다. 구문 강조를 표시하려면 자체 CSS 스타일시트를 가져와야 합니다.

1. 사용 가능한 Prism 테마에서 미리 만들어진 스타일시트를 선택합니다.

2. 이 스타일시트를 프로젝트의 public/ 디렉터리에 추가합니다.

3. <link> 태그를 통해 레이아웃 컴포넌트의 페이지 <head>에 로드합니다. (Prism 기본 사용법을 확인하세요.)

Prism에서 지원하는 언어 목록에서 옵션과 사용법을 확인할 수도 있습니다.