코드 블록
문서 내에서 코드 블록을 사용하는 것은 매우 강력한 기능입니다 💪.
Code title
You can add a title to the code block by adding a title
key after the language (leave a space between them).
```jsx title="/src/components/HelloCodeTitle.js"
function HelloCodeTitle(props) {
return <h1>Hello, {props.name}</h1>;
}
```
function HelloCodeTitle(props) {
return <h1>Hello, {props.name}</h1>;
}
Syntax highlighting
코드 블록은 3개의 억음부호(`)로 감싼 텍스트 블록입니다. You may check out this reference for the specifications of MDX.
```js
console.log('Every repo must come with a mascot.');
```
Use the matching language meta string for your code block, and Docusaurus will pick up syntax highlighting automatically, powered by Prism React Renderer.
console.log('Every repo must come with a mascot.');
Theming
By default, the Prism syntax highlighting theme we use is Palenight. You can change this to another theme by passing theme
field in prism
as themeConfig
in your docusaurus.config.js.
For example, if you prefer to use the dracula
highlighting theme:
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.
Supported Languages
By default, Docusaurus comes with a subset of commonly used languages.
자바, C#, PHP 같은 일부 인기있는 언어도 기본적으로 활성화되지 않습니다.
To add syntax highlighting for any of the other Prism-supported languages, define it in an array of additional languages.
각 추가적인 언어는 유효한 Prism 컴포넌트 이름이어야 합니다. For example, Prism would map the language cs
to csharp
, but only prism-csharp.js
exists as a component, so you need to use additionalLanguages: ['csharp']
. You can look into node_modules/prismjs/components
to find all components (languages) available.
예를 들어 PowerShell 언어에 대한 구문 강조를 추가하려면 아래와 같이 설정합니다.
export default {
// ...
themeConfig: {
prism: {
additionalLanguages: ['powershell'],
},
// ...
},
};
After adding additionalLanguages
, restart Docusaurus.
If you want to add highlighting for languages not yet supported by Prism, you can swizzle 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
It will produce prism-include-languages.js
in your src/theme
folder. You can add highlighting support for custom languages by editing prism-include-languages.js
:
const prismIncludeLanguages = (Prism) => {
// ...
additionalLanguages.forEach((lang) => {
require(`prismjs/components/prism-${lang}`);
});
require('/path/to/your/prism-language-definition');
// ...
};
You can refer to Prism's official language definitions when you are writing your own language definitions.
When adding a custom language definition, you do not need to add the language to the additionalLanguages
config array, since Docusaurus only looks up the additionalLanguages
strings in languages that Prism provides. Adding the language import in prism-include-languages.js
is sufficient.
Line highlighting
Highlighting with comments
You can use comments with highlight-next-line
, highlight-start
, and highlight-end
to select which lines are highlighted.
```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 | <!-- ... --> |
We will do our best to infer which set of comment styles to use based on the language, and default to allowing all comment styles. 현재 지원되지 않는 주석 스타일은 추가할 수 있도록 열려있습니다! 풀 리퀘스트를 환영합니다. 다른 주석 스타일도 의미적인 차이는 없으며 내용만 다릅니다.
You can set your own background color for highlighted code line in your src/css/custom.css
which will better fit to your selected syntax highlighting theme. 아래 예제에서 사용한 색상은 기본 구문 강조 테마(Palenight)에 맞춘 색상입니다. 다른 테마를 사용한다면 적절한 색상으로 수정해주어야 합니다.
:root {
--docusaurus-highlighted-code-line-bg: rgb(72, 77, 91);
}
/* If you have a different syntax highlighting theme for dark mode. */
[data-theme='dark'] {
/* Color which works with dark mode syntax highlighting theme */
--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.
Highlighting with metadata string
언어 메타 문자열 내에서 강조 표시된 라인 범위를 지정할 수도 있습니다(언어 뒤에 공백을 둡니다). 여러 라인을 강조하고 싶다면 라 인 번호를 콤마로 구분하거나 범위 구문을 사용해 설정합니다. This feature uses the parse-number-range
library and you can find more syntax on their project details.
```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';
}
```
아래에서 매직 주석 시스템을 확장해 사용자 지정 지시문과 그 기능을 정의하는 방법을 소개합니다. 하이라이트 메타 문자열이 없는 경우에만 매직 주석이 구문 분석을 처리합니다.
Custom magic comments
// highlight-next-line
and // highlight-start
etc. are called "magic comments", because they will be parsed and removed, and their purposes are to add metadata to the next line, or the section that the pair of start- and end-comments enclose.
테마 설정을 통해 사용자 지정 매직 주석을 선언할 수 있습니다. For example, you can register another magic comment that adds a code-block-error-line
class name:
- 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',
},
],
},
},
};