Starlight | Power the code block

“Expressive Code”라는 라이브러리는 공식 레포에서 다음과 같이 설명한다:

Expressive Code is an engine for presenting source code on the web, aiming to make your code easy to understand and visually stunning.

즉, 이 라이브러리는 코드 블록을 더 매력적으로 만드는 추가적인 스타일링과 다양한 기능을 제공한다. Next.js와 Astro와 같이 Rehype 플러그인을 지원하는 다양한 프레임워크에서 사용할 수 있으며, Astro를 기반으로 하는 Starlight에서는 기본 코드 블록 렌더링 엔진으로 사용한다.

Expressive Code는 다양한 기능을 제공하지만, 기본 상태에서는 없는 두 가지 공식 추가 기능(플러그인)이 있다. 이 글에서는 Starlight에서 이 추가적인 기능을 사용하는 방법을 소개한다.

두 플러그인은 다음과 같다:

Collapsible Sections (줄 범위 축소)
: 긴 코드 예제에서 특정 줄 범위를 축소하여, 핵심 부분에 집중하도록 돕는 기능
Line Numbers (줄 번호 표시)
: 코드 블록에 줄 번호를 표시하여, 코드의 특정 위치를 쉽게 참조할 수 있도록 하는 기능

사용 모습 참고

어떤 모습인지부터 보면 더 직관적으로 각 플러그인의 의의를 이해할 수 있다.
아래의 공식 문서에서 예시를 확인할 수 있다.

설치

플러그인을 활성화하는 방법을 서술한다.
”Expressive Code”의 공식 문서와 달리, 두 플러그인을 분리하지 않고 모두 설치하는 상황으로 가정한다.

또한, Starlight에서는 Expressive Code가 이미 설치되어 있음에 따라 추가 플러그인 설치로 바로 넘어간다.

npm i @expressive-code/plugin-collapsible-sections
npm i @expressive-code/plugin-line-numbers

설치 후 ec.config.mjs 파일을 생성해 다음과 같이 설정한다:

1
import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections'
2
import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers'
3

4
/** @type {import('@astrojs/starlight/expressive-code').StarlightExpressiveCodeOptions} */
5
export default {
6
  plugins: [pluginCollapsibleSections(), pluginLineNumbers()],
10 collapsed lines
7
  defaultProps: {
8
    // Disable line numbers by default
9
    showLineNumbers: false,
10
    // But enable line numbers for certain languages
11
    overridesByLang: {
12
      'js,ts,html,python': {
13
        showLineNumbers: true,
14
      },
15
    },
16
  },
17
}

7~16번 줄은 추가적인 플러그인 설정 부분으로, 선택 사항이다. 위 예시에서는 코드 블록 생성 시 기본적으로는 줄 번호를 표시하지 않지만, JavaScript, TypeScript, HTML, Python 언어를 표시하는 코드 블록에 대해서는 줄 번호를 표시하도록 설정했다.

사용 예시

아래는 Starlight에서 코드 블록을 렌더링할 때, 위에서 설정한 플러그인 기능을 사용하는 예시이다.
더 자세한 사용법은 Expressive Code 문서를 참고한다.

예시 1

```js showLineNumbers=true collapse={7-8} collapseStyle="collapsible-start"
function exampleFunction() {
  console.log("This is an example function.");
    ⋮
}
```

1
function exampleFunction() {
2
  console.log("This is an example function.");
3
  console.log("It has multiple lines of code.");
4
  console.log("Some lines can be collapsed.");
5
  console.log("This is the last line before collapse.");
2 collapsed lines
6
  // This line will be collapsed
7
  console.log("This line is hidden by default.");
8
}

예시 2

```js showLineNumbers=false collapse={6-7} collapseStyle="github"
function anotherExampleFunction() {
  console.log("This is another example function.");
    ⋮
}
```

function anotherExampleFunction() {
  console.log("This is another example function.");
  // The two lines under are collapsed until expanded
  // ("github" style, irreversible)
2 collapsed lines
  console.log("It also has multiple lines of code.");
  console.log("This line is hidden by default.");
}