버전: 3.5.2

코드 블록

문서 내에서 코드 블록을 사용하는 것은 매우 강력한 기능입니다 💪.

코드 제목

언어 이름 뒤에 title 키를 추가하면 코드 블록에 제목을 붙일 수 있습니다(둘 사이에 공백을 넣으세요).

```jsx title="/src/components/HelloCodeTitle.js"
function HelloCodeTitle(props) {
  return <h1>안녕하세요, {props.name}</h1>;
}
```

http://localhost:3000

/src/components/HelloCodeTitle.js
function HelloCodeTitle(props) {
  return <h1>안녕하세요, {props.name}</h1>;
}

구문 강조

코드 블록은 3개의 억음부호(`)로 감싼 텍스트 블록입니다. You may check out this reference for the specifications of MDX.

```js
console.log('Every repo must come with a mascot.');
```

코드 블록에 해당 언어의 메타 문자열을 지정하면 도큐사우루스가 Prism React Renderer를 사용해 구문 강조를 자동으로 적용합니다.

http://localhost:3000

console.log('Every repo must come with a mascot.');

테마

기본으로 사용하는 Prism 구문 강조 테마는 Palenight입니다. You can change this to another theme by passing theme field in prism as themeConfig in your docusaurus.config.js.

예를 들어 dracula 구문 강조 테마를 사용하고 싶다면 다음과 같이 설정하세요:

docusaurus.config.js
import {themes as prismThemes} from 'prism-react-renderer';

export default {
  themeConfig: {
    prism: {
      theme: prismThemes.dracula,
    },
  },
};

Prism 테마는 JS 오브젝트일 뿐이므로 기본 설정이 맘에 들지 않는다면 자신만의 테마를 만들 수 있습니다. 도큐사우루스는 github와 vsDark 테마를 확장해 더 풍부한 구문 강조를 제공합니다. 라이트 및 다크 코드 블록 테마 구현을 확인할 수 있습니다.

지원 언어

By default, Docusaurus comes with a subset of commonly used languages.

경고

자바, C#, PHP 같은 일부 인기있는 언어도 기본적으로 활성화되지 않습니다.

그 밖의 Prism 지원 언어에 구문 강조를 추가하려면 추가 언어 배열에 해당 언어를 지정하세요.

참고

각 추가적인 언어는 유효한 Prism 컴포넌트 이름이어야 합니다. 예를 들어 Prism은 언어 cs를 csharp에 매핑하지만, _컴포넌트_로는 prism-csharp.js만 존재하므로 additionalLanguages: ['csharp']를 사용해야 합니다. 사용할 수 있는 모든 컴포넌트(언어)는 node_modules/prismjs/components에서 확인할 수 있습니다.

예를 들어 PowerShell 언어에 대한 구문 강조를 추가하려면 아래와 같이 설정합니다.

docusaurus.config.js
export default {
  // ...
  themeConfig: {
    prism: {
      additionalLanguages: ['powershell'],
    },
    // ...
  },
};

additionalLanguages를 추가한 뒤 도큐사우루스를 다시 시작하세요.

Prism이 아직 지원하지 않는 언어에 구문 강조를 추가하려면 prism-include-languages를 swizzle할 수 있습니다:

npm
Yarn
pnpm
Bun

npm run swizzle @docusaurus/theme-classic prism-include-languages

yarn swizzle @docusaurus/theme-classic prism-include-languages

pnpm run swizzle @docusaurus/theme-classic prism-include-languages

bun run swizzle @docusaurus/theme-classic prism-include-languages

그러면 prism-include-languages.js 파일이 src/theme 폴더에 생성됩니다. prism-include-languages.js를 편집해 사용자 정의 언어에 대한 구문 강조 지원을 추가할 수 있습니다:

src/theme/prism-include-languages.js
const prismIncludeLanguages = (Prism) => {
  // ...

  additionalLanguages.forEach((lang) => {
    require(`prismjs/components/prism-${lang}`);
  });

  require('/path/to/your/prism-language-definition');

  // ...
};

언어 정의를 직접 작성할 때 Prism의 공식 언어 정의를 참고할 수 있습니다.

직접 만든 언어 정의를 추가할 때는 해당 언어를 additionalLanguages 설정 배열에 넣을 필요가 없습니다. 도큐사우루스는 additionalLanguages의 문자열을 Prism이 제공하는 언어에서만 찾기 때문입니다. prism-include-languages.js에 언어 정의를 가져오는 코드를 추가하는 것만으로 충분합니다.

라인 강조

주석을 사용한 강조

highlight-next-line, highlight-start, highlight-end가 포함된 주석을 사용해 강조할 줄을 선택할 수 있습니다.

```js
function HighlightSomeText(highlight) {
  if (highlight) {
    // highlight-next-line
    return 'This text is highlighted!';
  }

  return 'Nothing highlighted';
}

function HighlightMoreText(highlight) {
  // highlight-start
  if (highlight) {
    return 'This range is highlighted!';
  }
  // highlight-end

  return 'Nothing highlighted';
}
```

http://localhost:3000

function HighlightSomeText(highlight) {
  if (highlight) {
    return 'This text is highlighted!';
  }

  return 'Nothing highlighted';
}

function HighlightMoreText(highlight) {
  if (highlight) {
    return 'This range is highlighted!';
  }

  return 'Nothing highlighted';
}

지원하는 주석 구문은 아래와 같습니다.

스타일	구문
C-style	`/* ... */` 및 `// ...`
JSX-style	`{/* ... */}`
Bash-style	`# ...`
HTML-style	`<!-- ... -->`

언어에 따라 사용할 주석 스타일을 최대한 추론하며, 기본적으로 모든 주석 스타일을 허용합니다. 현재 지원되지 않는 주석 스타일은 추가할 수 있도록 열려있습니다! 풀 리퀘스트를 환영합니다. 다른 주석 스타일도 의미적인 차이는 없으며 내용만 다릅니다.

선택한 구문 강조 테마에 더 잘 어울리도록 src/css/custom.css에서 강조 표시된 코드 줄의 배경색을 직접 설정할 수 있습니다. 아래 예제에서 사용한 색상은 기본 구문 강조 테마(Palenight)에 맞춘 색상입니다. 다른 테마를 사용한다면 적절한 색상으로 수정해주어야 합니다.

/src/css/custom.css
:root {
  --docusaurus-highlighted-code-line-bg: rgb(72, 77, 91);
}

/* 다크 모드용으로 다른 구문 강조 테마를 사용하는 경우. */
[data-theme='dark'] {
  /* 다크 모드 구문 강조 테마에 어울리는 색상 */
  --docusaurus-highlighted-code-line-bg: rgb(100, 100, 100);
}

If you also need to style the highlighted code line in some other way, you can target on theme-code-block-highlighted-line CSS class.

메타데이터 문자열로 강조하기

언어 메타 문자열 내에서 강조 표시된 라인 범위를 지정할 수도 있습니다(언어 뒤에 공백을 둡니다). 여러 라인을 강조하고 싶다면 라인 번호를 콤마로 구분하거나 범위 구문을 사용해 설정합니다. 이 기능은 parse-number-range 라이브러리를 사용하며, 해당 프로젝트의 상세 정보에서 더 많은 구문을 확인할 수 있습니다.

```jsx {1,4-6,11}
import React from 'react';

function MyComponent(props) {
  if (props.isBar) {
    return <div>Bar</div>;
  }

  return <div>Foo</div>;
}

export default MyComponent;
```

http://localhost:3000

import React from 'react';

function MyComponent(props) {
  if (props.isBar) {
    return <div>Bar</div>;
  }

  return <div>Foo</div>;
}

export default MyComponent;

주석 사용 권장

가능한 경우 주석으로 하이라이트 처리하는 것을 선호합니다. 코드 내에서 하이라이트를 처리하면 코드 블록이 길어지더라도 라인수를 직접 체크할 필요가 없습니다. 라인을 추가/제거할 때도 라인 범위를 다시 조정하지 않아도 됩니다.

- ```jsx {3}
+ ```jsx {4}
  function HighlightSomeText(highlight) {
    if (highlight) {
+     console.log('Highlighted text found');
      return 'This text is highlighted!';
    }

    return 'Nothing highlighted';
  }
  ```

아래에서 매직 주석 시스템을 확장해 사용자 지정 지시문과 그 기능을 정의하는 방법을 소개합니다. 하이라이트 메타 문자열이 없는 경우에만 매직 주석이 구문 분석을 처리합니다.

사용자 지정 매직 주석

// highlight-next-line과 // highlight-start 등은 파싱 후 제거되며, 다음 줄이나 시작 및 끝 주석 쌍으로 둘러싸인 구간에 메타데이터를 추가하는 용도로 사용되므로 "매직 주석"이라고 합니다.

테마 설정을 통해 사용자 지정 매직 주석을 선언할 수 있습니다. 예를 들어, code-block-error-line 클래스 이름을 추가하는 다른 매직 주석을 등록할 수 있습니다:

docusaurus.config.js
src/css/custom.css
myDoc.md

export default {
  themeConfig: {
    prism: {
      magicComments: [
        // 기본 강조 표시 클래스 이름에 대한 설정도 함께 포함하는 것을 잊지 마세요!
        {
          className: 'theme-code-block-highlighted-line',
          line: 'highlight-next-line',
          block: {start: 'highlight-start', end: 'highlight-end'},
        },
        {
          className: 'code-block-error-line',
          line: 'This will error',
        },
      ],
    },
  },
};

.code-block-error-line {
  background-color: #ff000020;
  display: block;
  margin: 0 calc(-1 * var(--ifm-pre-padding));
  padding: 0 var(--ifm-pre-padding);
  border-left: 3px solid #ff000080;
}

JavaScript에서 `null`의 속성에 접근하려고 하면 오류가 발생합니다.

```js
const name = null;
// This will error
console.log(name.toUpperCase());
// Uncaught TypeError: Cannot read properties of null (reading 'toUpperCase')
```

http://localhost:3000

자바스크립트에서 null 속성에 접근하려고 하면 오류가 발생합니다.

const name = null;
// 오류가 발생합니다.
console.log(name.toUpperCase());
// Uncaught TypeError: Cannot read properties of null (reading 'toUpperCase')

메타 문자열에 숫자 범위 ({1,3-4} 구문)를 사용하면, 도큐사우루스는 첫 번째 magicComments 항목의 클래스 이름을 적용합니다. 기본값은 theme-code-block-highlighted-line이지만, magicComments 설정을 변경해 다른 항목을 첫 번째에 배치하면 메타 문자열 범위의 의미도 바뀝니다.

magicComments: []를 사용해 기본 제공되는 줄 강조 표시용 주석을 비활성화할 수 있습니다. 매직 주석 구성은 없지만 도큐사우루스가 메타 문자열 범위를 포함하는 코드 블록을 발견하면 적용할 클래스 이름이 없기 때문에 오류가 발생합니다. 강조 표시되는 클래스 이름은 결국 매직 주석 항목일 뿐입니다.

Every magic comment entry will contain three keys: className (required), line, which applies to the directly next line, or block (containing start and end), which applies to the entire block enclosed by the two comments.

CSS로 해당 클래스에 스타일을 적용하는 것만으로도 많은 작업을 할 수 있지만, swizzling을 통해 이 기능의 잠재력을 온전히 활용할 수 있습니다.

npm
Yarn
pnpm
Bun

npm run swizzle @docusaurus/theme-classic CodeBlock/Line

yarn swizzle @docusaurus/theme-classic CodeBlock/Line

pnpm run swizzle @docusaurus/theme-classic CodeBlock/Line

bun run swizzle @docusaurus/theme-classic CodeBlock/Line

Line 컴포넌트는 클래스 이름 목록을 전달받으므로, 이를 기준으로 조건에 따라 서로 다른 마크업을 렌더링할 수 있습니다.

줄 번호 매기기

언어 메타 문자열에 showLineNumbers 키를 넣으면 코드 블록에 줄 번호를 표시할 수 있습니다(키 바로 앞에 공백을 넣는 것을 잊지 마세요).

```jsx {1,4-6,11} showLineNumbers
import React from 'react';

function MyComponent(props) {
  if (props.isBar) {
    return <div>Bar</div>;
  }

  return <div>Foo</div>;
}

export default MyComponent;
```

http://localhost:3000

import React from 'react';

function MyComponent(props) {
  if (props.isBar) {
    return <div>Bar</div>;
  }

  return <div>Foo</div>;
}

export default MyComponent;

대화형 코드 편집기

(React Live 기반)

@docusaurus/theme-live-codeblock 플러그인으로 상호작용형 코드 편집기를 만들 수 있습니다. 먼저 패키지에 플러그인을 추가해주세요.

npm
Yarn
pnpm
Bun

npm install --save @docusaurus/theme-live-codeblock

yarn add @docusaurus/theme-live-codeblock

pnpm add @docusaurus/theme-live-codeblock

bun add @docusaurus/theme-live-codeblock

docusaurus.config.js에도 플러그인을 추가해야 합니다.

export default {
  // ...
  themes: ['@docusaurus/theme-live-codeblock'],
  // ...
};

플러그인을 사용하려면 언어 메타 문자열에 live를 붙인 코드 블록을 만드세요.

```jsx live
function Clock(props) {
  const [date, setDate] = useState(new Date());
  useEffect(() => {
    const timerID = setInterval(() => tick(), 1000);

    return function cleanup() {
      clearInterval(timerID);
    };
  });

  function tick() {
    setDate(new Date());
  }

  return (
    <div>
      <h2>It is {date.toLocaleTimeString()}.</h2>
    </div>
  );
}
```

코드 블록은 대화형 편집기로 변환됩니다. 코드를 변경하면 바로 결과창에 표시됩니다.

http://localhost:3000

라이브 에디터

function Clock(props) {
  const [date, setDate] = useState(new Date());
  useEffect(() => {
    const timerID = setInterval(() => tick(), 1000);

    return function cleanup() {
      clearInterval(timerID);
    };
  });

  function tick() {
    setDate(new Date());
  }

  return (
    <div>
      <h2>It is {date.toLocaleTimeString()}.</h2>
    </div>
  );
}

결과

가져오기

react-live와 import

react-live 코드 편집기를 직접 가져올 수는 없습니다. 가져오기 할 항목을 미리 정의해야 합니다.

기본적으로 모든 리액트 가져오기를 지원합니다. 가져오기 기능을 사용하려면 react-live scope를 대체해주어야 합니다.

npm
Yarn
pnpm
Bun

npm run swizzle @docusaurus/theme-live-codeblock ReactLiveScope -- --eject

yarn swizzle @docusaurus/theme-live-codeblock ReactLiveScope --eject

pnpm run swizzle @docusaurus/theme-live-codeblock ReactLiveScope --eject

bun run swizzle @docusaurus/theme-live-codeblock ReactLiveScope --eject

src/theme/ReactLiveScope/index.js
import React from 'react';

const ButtonExample = (props) => (
  <button
    {...props}
    style={{
      backgroundColor: 'white',
      color: 'black',
      border: 'solid red',
      borderRadius: 20,
      padding: 10,
      cursor: 'pointer',
      ...props.style,
    }}
  />
);

// react-live에 필요한 import 항목을 여기에 추가하세요
const ReactLiveScope = {
  React,
  ...React,
  ButtonExample,
};

export default ReactLiveScope;

이제 ButtonExample 컴포넌트를 사용할 수 있습니다:

http://localhost:3000

라이브 에디터

function MyPlayground(props) {
  return (
    <div>
      <ButtonExample onClick={() => alert('안녕하세요!')}>눌러 보세요</ButtonExample>
    </div>
  );
}

결과

렌더링 명령(noInline)

코드에 여러 컴포넌트나 변수가 포함된 경우 오류를 방지하려면 noInline 옵션을 사용해야 합니다.

```jsx live noInline
const project = 'Docusaurus';

const Greeting = () => <p>안녕하세요 {project}!</p>;

render(<Greeting />);
```

일반적인 상호작용형 코드 블록과 달리, noInline을 사용하면 React Live는 렌더링을 위해 코드를 인라인 함수로 감싸지 않습니다.

출력을 표시하려면 코드 끝에서 render()를 명시적으로 호출해야 합니다.

http://localhost:3000

라이브 에디터

const project = "Docusaurus";

const Greeting = () => (
  <p>안녕하세요 {project}!</p>
);

render(
  <Greeting />
);

결과

코드 블록 내에서 JSX 마크업 사용하기

마크다운 코드 블록은 항상 내용을 일반 텍스트로 유지하기 때문에 다음과 같은 작업은 할 수 없습니다.

type EditUrlFunction = (params: {
  // 이 부분은 링크로 변환되지 않습니다 (그럴 만한 이유가 있습니다!)
  version: <a href="/docs/versioning">버전</a>;
  versionDocsDirPath: string;
  docPath: string;
  permalink: string;
  locale: string;
}) => string | undefined;

앵커 링크나 굵은 글씨 같은 HTML 마크업을 삽입하려면, \<pre> 태그, \<code> 태그 또는 \<CodeBlock> 컴포넌트를 사용할 수 있습니다.

<pre>
  <b>입력: </b>1 2 3 4{'\n'}
  <b>출력: </b>"366300745"{'\n'}
</pre>

http://localhost:3000

입력: 1 2 3 4
출력: "366300745"

MDX는 공백에 민감하지 않습니다

MDX는 JSX와 같은 방식으로 동작합니다: 줄바꿈 문자는 \<pre> 안에 있더라도 공백으로 바뀝니다. 필요하다면 줄바꿈 문자를 명시적으로 작성해야 합니다.

경고

구문 강조 표시는 일반 문자열에서만 작동합니다. 도큐사우루스는 JSX 자식을 포함하는 코드 블록 콘텐츠의 구문 분석은 하지 않습니다.

코드 블록 내에서 여러 프로그래밍 언어 지원하기

MDX를 사용하면 문서 내에서 대화형 컴포넌트를 쉽게 만들 수 있습니다. 이를테면 여러 프로그래밍 언어의 코드를 보여주기 위해 탭 컴포넌트를 사용해서 사용자가 선택하게 할 수 있습니다.

여러 언어를 지원하는 코드 블록 전용 컴포넌트를 구현하는 대신, 코드가 아닌 다른 용도에도 사용할 수 있도록 클래식 테마에 범용 \<Tabs> 컴포넌트를 구현했습니다.

아래 예제는 문서 내에서 여러 프로그래밍 언어를 지원하는 코드를 어떻게 처리할 수 있는지 보여줍니다. 각 언어 블록의 위아래 빈 줄은 의도적으로 넣은 것입니다. 이는 현재 MDX의 제한 사항입니다: MDX 파서가 JSX가 아닌 Markdown 구문으로 인식할 수 있도록 Markdown 구문 주위에 빈 줄을 넣어야 합니다.

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
<TabItem value="js" label="JavaScript">

```js
function helloWorld() {
  console.log('안녕하세요, 세상!');
}
```

</TabItem>
<TabItem value="py" label="Python">

```py
def hello_world():
  print("안녕하세요, 세상!")
```

</TabItem>
<TabItem value="java" label="Java">

```java
class HelloWorld {
  public static void main(String args[]) {
    System.out.println("안녕하세요, 세상");
  }
}
```

</TabItem>
</Tabs>

화면에 보여지는 결과는 아래와 같습니다.

http://localhost:3000

JavaScript
Python
Java

function helloWorld() {
  console.log('Hello, world!');
}

def hello_world():
  print("Hello, world!")

class HelloWorld {
  public static void main(String args[]) {
    System.out.println("Hello, World");
  }
}

이러한 다중 언어 코드 탭이 여러 개 있고 탭 인스턴스 간에 선택 항목을 동기화하고 싶다면, 탭 선택 동기화 섹션을 참조하세요.

도큐사우루스 npm2yarn remark 플러그인

npm과 Yarn 모두 CLI 명령을 표시하는 것은 매우 일반적인 요구 사항입니다. 예를 들면 다음과 같은 형식입니다.

npm
Yarn
pnpm
Bun

npm install @docusaurus/remark-plugin-npm2yarn

yarn add @docusaurus/remark-plugin-npm2yarn

pnpm add @docusaurus/remark-plugin-npm2yarn

bun add @docusaurus/remark-plugin-npm2yarn

도큐사우루스는 이러한 유틸리티를 기본으로 제공하므로 매번 Tabs 컴포넌트를 사용할 필요가 없습니다. 이 기능을 활성화하려면 먼저 위에서 설명한 대로 @docusaurus/remark-plugin-npm2yarn 패키지를 설치한 다음, docusaurus.config.js에서 이 기능이 필요한 플러그인(문서, 블로그, 페이지 등)의 remarkPlugins 옵션에 등록하세요. (설정 형식에 대한 자세한 내용은 문서 설정을 참조하세요)

docusaurus.config.js
export default {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          remarkPlugins: [
            [require('@docusaurus/remark-plugin-npm2yarn'), {sync: true}],
          ],
        },
        pages: {
          remarkPlugins: [require('@docusaurus/remark-plugin-npm2yarn')],
        },
        blog: {
          remarkPlugins: [
            [
              require('@docusaurus/remark-plugin-npm2yarn'),
              {converters: ['pnpm']},
            ],
          ],
          // ...
        },
      },
    ],
  ],
};

그런 다음 코드 블록에 npm2yarn 키를 추가해 사용하세요:

```bash npm2yarn
npm install @docusaurus/remark-plugin-npm2yarn
```

설정

옵션	타입	기본값	설명
`sync`	`boolean`	`false`	선택한 컨버터를 모든 코드 블록에 동기화할지 여부를 설정합니다.
`converters`	`array`	`'yarn'`, `'pnpm'`	사용할 컨버터 목록입니다. 첫 번째 컨버터가 기본 선택으로 사용되므로 컨버터 목록의 순서가 중요합니다.

JSX 사용하기

Markdown 밖에서도 @theme/CodeBlock 컴포넌트를 사용해 같은 출력을 얻을 수 있습니다.

import CodeBlock from '@theme/CodeBlock';

export default function MyReactPage() {
  return (
    <div>
      <CodeBlock
        language="jsx"
        title="/src/components/HelloCodeTitle.js"
        showLineNumbers>
        {`function HelloCodeTitle(props) {
  return <h1>안녕하세요, {props.name}</h1>;
}`}
      </CodeBlock>
    </div>
  );
}

http://localhost:3000

/src/components/HelloCodeTitle.js
function HelloCodeTitle(props) {
return <h1>안녕하세요, {props.name}</h1>;
}

사용할 수 있는 props는 language, title, showLineNumbers이며, Markdown 코드 블록을 작성할 때와 같은 방식으로 지정합니다.

권장하지는 않지만, metastring prop을 metastring='{1-2} title="/src/components/HelloCodeTitle.js" showLineNumbers'와 같은 형태로 전달할 수도 있습니다. 이는 Markdown 코드 블록이 내부적으로 처리되는 방식입니다. 다만 주석을 사용해 줄을 강조하는 방법을 권장합니다.

As previously stated, syntax highlighting is only applied when the children is a simple string.

코드 제목​

구문 강조​

테마​

지원 언어​

라인 강조​

주석을 사용한 강조​

메타데이터 문자열로 강조하기​

사용자 지정 매직 주석​

줄 번호 매기기​

대화형 코드 편집기​

가져오기​

렌더링 명령(noInline)​

코드 블록 내에서 JSX 마크업 사용하기​

코드 블록 내에서 여러 프로그래밍 언어 지원하기​

도큐사우루스 npm2yarn remark 플러그인​

설정​

JSX 사용하기​

코드 제목

구문 강조

테마

지원 언어

라인 강조

주석을 사용한 강조

메타데이터 문자열로 강조하기

사용자 지정 매직 주석

줄 번호 매기기

대화형 코드 편집기

가져오기

렌더링 명령(noInline)

코드 블록 내에서 JSX 마크업 사용하기

코드 블록 내에서 여러 프로그래밍 언어 지원하기

도큐사우루스 npm2yarn remark 플러그인

설정

JSX 사용하기