코드 블록
문서 내에서 코드 블록을 사용하는 것은 매우 강력한 기능입니다 💪.
코드 제목
프로그래밍 언어 설정 뒤에 title
항목을 입력(공백 문자로 구분합니다)하면 코드 블록 내에 제목을 추가할 수 있습니다.
```jsx title="/src/components/HelloCodeTitle.js"
function HelloCodeTitle(props) {
return <h1>Hello, {props.name}</h1>;
}
```
function HelloCodeTitle(props) {
return <h1>Hello, {props.name}</h1>;
}
구문 강조
코드 블록은 3개의 억음부호(`)로 감싼 텍스트 블록입니다. 문법과 관련된 내용은 MDX 명세서를 참조하세요.
```js
console.log('Every repo must come with a mascot.');
```
코드 블록에서 사용할 적절한 프로그래밍 언어 메타 문자열을 설정해주면 도큐사우루스에서는 Prism React Renderer를 사용해 자동으로 구문 강조를 처리합니다.
console.log('Every repo must come with a mascot.');
테마
By default, the Prism syntax highlighting theme we use is Palenight. docusaurus.config.js 파일에서 themeConfig
항목 안에 prism
항목을 찾아서 theme
항목을 수정하면 다른 테마를 적용할 수 있습니다.
예를 들어 구문 강조 테마를 dracula
로 적용하고 싶다면 아래와 같이 설정합니다.
import {themes as prismThemes} from 'prism-react-renderer';
export default {
themeConfig: {
prism: {
theme: prismThemes.dracula,
},
},
};
Prism 테마는 JS 오브젝트일 뿐이므로 기본 설정이 맘에 들지 않는다면 자신만의 테마를 만들 수 있습니다. Docusaurus enhances the github
and vsDark
themes to provide richer highlight, and you can check our implementations for the light and dark code block themes.
지원 언어
By default, Docusaurus comes with a subset of commonly used languages.
자바, C#, PHP 같은 일부 인기있는 언어도 기본적으로 활성화되지 않습니다.
Prism 지원 프로그래밍 언어 목록에 포함된 언어의 구문 강조를 추가하고 싶다면 배열 형태로 항목 설정을 추가합니다.
각 추가적인 언어는 유효한 Prism 컴포넌트 이름이어야 합니다. 예를 들어 Prism은 language cs
를 csharp
에 연결하지만 prism-csharp.js
만 _컴포넌트_로 제공되므로 additionalLanguages: ['csharp']
를 사용해야 합니다. node_modules/prismjs/components
에서 사용할 수 있는 모든 컴포넌트(언어)를 확인할 수 있습니다.
예를 들어 PowerShell 언어에 대한 구문 강조를 추가하려면 아래와 같이 설정합니다.
export default {
// ...
themeConfig: {
prism: {
additionalLanguages: ['powershell'],
},
// ...
},
};
additionalLanguages
을 추가하면 도큐사우루스를 재시작합니다.
Prism에서 지원하지 않는 프로그래밍 언어의 구문 강조를 추가하고 싶다면 prism-include-languages
를 아래와 같이 대체할 수 있습니다.
- npm
- Yarn
- pnpm
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
명령을 실행하면 src/theme
디렉터리 안에 prism-include-languages.js
파일을 만듭니다. prism-include-languages.js
파일을 수정해서 원하는 프로그래밍 언어에 대한 구문 강조를 추가할 수 있습니다.
const prismIncludeLanguages = (Prism) => {
// ...
additionalLanguages.forEach((lang) => {
require(`prismjs/components/prism-${lang}`);
});
require('/path/to/your/prism-language-definition');
// ...
};
해당 언어에 대한 구문 강조 스크립트 작성 시에는 Prism official language definitions를 참조하세요.
사용자 정의 언어 정의를 추가할 때는 도큐사우루스가 Prism에서 제공하는 언어의 additionalLanguages
문자열만 찾기 때문에 additionalLanguages
설정 배열값에 해당 언어를 추가할 필요는 없습니다. 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';
}
```
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 | /* ... */ and // ... |
JSX-style | {/* ... */} |
Bash-style | # ... |
HTML-style | <!-- ... --> |
언어에 따라 사용할 주석 스타일 집합을 대응할 수 있도록 최선을 다할 것이며 기본적으로 모든 주석 스타일을 허용합니다. 현재 지원되지 않는 주석 스타일은 추가할 수 있도록 열려있습니다! 풀 리퀘스트를 환영합니다. 다른 주석 스타일도 의미적인 차이는 없으며 내용만 다릅니다.
src/css/custom.css
에서 강조 표시된 코드 라인의 배경색을 설정하면 선택한 구문 강조 테마에 더 잘 맞습니다. 아래 예제에서 사용한 색상은 기본 구문 강조 테마(Palenight)에 맞춘 색상입니다. 다른 테마를 사용한다면 적절한 색상으로 수정해주어야 합니다.
:root {
--docusaurus-highlighted-code-line-bg: rgb(72, 77, 91);
}
/* 어두운 모드에 대해 다른 구문 강조 테마가 있는 경우 */
[data-theme='dark'] {
/* 어두운 모드 구문 강조 테마와 함께 작동하는 색상 */
--docusaurus-highlighted-code-line-bg: rgb(100, 100, 100);
}
강조 표시된 코드 라인을 다른 방식으로 스타일 지정해야 하는 경우 theme-code-block-highlighted-line
CSS 클래스를 대상으로 지정할 수 있습니다.
메타데이터 문자열로 강조하기
언어 메타 문자열 내에서 강조 표시된 라인 범위를 지정할 수도 있습니다(언어 뒤에 공백을 둡니다). 여러 라인을 강조하고 싶다면 라인 번호를 콤마로 구분하거나 범위 구문을 사용해 설정합니다. 이 기능에서는 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;
```
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
등은 구문 분석 후 제거되기 때문에 "매직 주석"이라고 하며 다음 줄 또는 start-주석과 end- 주석으로 묶인 섹션에 메타데이터를 추가하는 것입니다.
테마 설정을 통해 사용자 지정 매직 주석을 선언할 수 있습니다. 예를 들어 code-block-error-line
클래스 이름을 추가하는 다른 매직 주석을 등록할 수 있습니다.
- docusaurus.config.js
- src/css/custom.css
- myDoc.md
export default {
themeConfig: {
prism: {
magicComments: [
// Remember to extend the default highlight class name as well!
{
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;
}
자바스크립트에서 `null` 속성에 접근하려고 하면 오류가 발생합니다.
```js
const name = null;
// 오류가 발생합니다.
console.log(name.toUpperCase());
// Uncaught TypeError: Cannot read properties of null (reading 'toUpperCase')
```
자바스크립트에서 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: []
를 사용해 주석을 강조 표시하는 기본 줄을 비활성화할 수 있습니다. 매직 주석 구성은 없지만 도큐사우루스가 메타 문자열 범위를 포함하는 코드 블록을 발견하면 적용할 클래스 이름이 없기 때문에 오류가 발생합니다. 강조 표시되는 클래스 이름은 결국 매직 주석 항목일 뿐입니다.
모든 매직 주석 항목은 3개의 키가 포함됩니다. className
(필수), 바로 다음 줄에 적용되는 line
또는 두 개의 주석으로 묶인 전체 블록에 적용되는 block
(start
와 end
포함)입니다.
CSS를 사용해 클래스로 지정한 항목에 이미 많은 일을 할 수 있지만 스위즐링을 통해 이 기능의 잠재력을 최대한 활용할 수 있습니다.
- npm
- Yarn
- pnpm
npm run swizzle @docusaurus/theme-classic CodeBlock/Line
yarn swizzle @docusaurus/theme-classic CodeBlock/Line
pnpm run swizzle @docusaurus/theme-classic CodeBlock/Line
Line
컴포넌트는 조건에 따라 다른 마크업을 렌더링할 수 있는 클래스 이름 목록을 받습니다.
줄 번호 매기기
language 메타 문자열(키 바로 앞에 공백을 추가하는 것을 잊지 마세요) 내에서 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;
```
import React from 'react';
function MyComponent(props) {
if (props.isBar) {
return <div>Bar</div>;
}
return <div>Foo</div>;
}
export default MyComponent;
대화형 코드 편집기
(Powered by React Live)
@docusaurus/theme-live-codeblock
플러그인을 사용해 대화형 코드 편집기를 만들 수 있습니다. 먼저 패키지에 플러그인을 추가해주세요.
- npm
- Yarn
- pnpm
npm install --save @docusaurus/theme-live-codeblock
yarn add @docusaurus/theme-live-codeblock
pnpm add @docusaurus/theme-live-codeblock