마크다운 기능
도큐사우루스는 **Markdown**을 주요 콘텐츠 작성 형식으로 사용합니다.
도큐사우루스는 최신 도구를 활용해 상호작용형 문서를 만들 수 있도록 돕습니다.
MDX 컴파일러는 Markdown 파일을 React 컴포넌트로 변환하며, Markdown 콘텐츠에서 JSX를 사용할 수 있게 해 줍니다. 이를 통해 콘텐츠 곳곳에 React 컴포넌트를 쉽게 넣어 즐거운 학습 경험을 만들 수 있습니다.
**MDX 플레이그라운드**가 여러분의 새로운 단짝입니다!
MDX 컴파일러가 Markdown을 React로 변환하는 방식을 보여 주는 매우 유용한 디버깅 도구입니다.
옵션: 알맞은 형식(MDX 또는 CommonMark)을 선택하고, 도큐사우루스에서 사용하는 다음 플러그인도 선택하세요: remark-gfm, remark-directive, rehype-raw.
MDX와 CommonMark 비교
도큐사우루스는 MDX 컴파일러로 .md와 .mdx 파일을 모두 React 컴포넌트로 컴파일하지만, 설정에 따라 구문이 다르게 해석될 수 있습니다.
MDX 컴파일러는 2가지 형식을 지원합니다:
- MDX 형식: JSX 사용을 지원하는 강력한 파서
- CommonMark 형식: JSX 사용을 허용하지 않는 표준 준수 Markdown 파서
By default, Docusaurus v3 uses the MDX format for all files (including .md files) for historical reasons.
siteConfig.markdown.format 설정이나 mdx.format: md 프런트 매터를 사용해 CommonMark 사용을 선택할 수 있습니다.
CommonMark를 사용할 계획이라면 siteConfig.markdown.format: 'detect' 설정을 권장합니다. 파일 확장자에 따라 알맞은 형식이 자동으로 선택됩니다:
.md파일은 CommonMark 형식을 사용합니다.mdx파일은 MDX 형식을 사용합니다
CommonMark 지원은 실험적이며 현재 몇 가지 제한 사항이 있습니다.
기본 기능
Markdown은 읽기 쉬운 구문으로 서식이 있는 콘텐츠를 작성할 수 있게 해 주는 문법입니다.
### My Doc Section
Hello world message with some **bold** text, some _italic_ text, and a [link](/)
Markdown은 선언적입니다
일부는 Markdown과 HTML이 1-1로 대응한다고 가정하고, 예를 들어 가 항상 <img src="/img/docusaurus.png" alt="Preview" />로 그대로 변환된다고 생각할 수 있습니다. 하지만, 실제로는 그렇지 않습니다.
Markdown 구문 는 여기에 이미지를 삽입해야 한다고 도큐사우루스에 선언적으로 알려줄 뿐이지만, 파일 경로를 URL 경로로 변환하는 등의 추가 처리가 이루어질 수 있으므로, 생성된 마크업은 다른 Markdown 렌더러의 출력이나 단순히 해당 JSX/HTML 코드로 직접 옮긴 결과와 다를 수 있습니다.
일반적으로 마크업의 의미 (```로 둘러싸면 코드 블록이 되고; >는 인용 단락이 되는 등)만 가정해야 하며, 실제 컴파일된 출력까지 가정해서는 안 됩니다.
프런트 매터
프런트 매터는 Markdown 파일에 메타데이터를 추가하는 데 사용됩니다. 모든 콘텐츠 플러그인은 자체 프런트 매터 스키마를 가지며, 프런트 매터를 사용해 콘텐츠나 다른 설정에서 추론한 기본 메타데이터를 보완합니다.
프런트 매터는 파일 맨 위에 작성하며, 대시 세 개로 이루어진 ---로 감쌉니다. 내용은 YAML로 파싱됩니다.
---
title: My Doc Title
more_data:
- Can be provided
- as: objects
or: arrays
---
각 공식 플러그인의 API 문서에는 지원하는 속성이 나열되어 있습니다:
Markdown 설정의 parseFrontMatter 함수를 사용해 자체 프런트 매터 파서를 제공하거나, 기본 파서를 확장하세요.
기본 파서를 재사용하면서 이를 자체적인 맞춤 로직으로 감쌀 수 있습니다. 이를 통해 편리한 프런트 매터 변환이나 축약 설정을 구현하거나, 도큐사우루스 플러그인이 지원하지 않는 프런트 매터를 사용하는 외부 시스템과 연동할 수 있습니다.
export default {
markdown: {
parseFrontMatter: async (params) => {
// 기본 파서 재사용
const result = await params.defaultParseFrontMatter(params);
// 프런트 매터의 description 플레이스홀더 처리
result.frontMatter.description =
result.frontMatter.description?.replaceAll('{{MY_VAR}}', 'MY_VALUE');
// 나만의 프런트 매터 축약 설정 만들기
if (result.frontMatter.i_do_not_want_docs_pagination) {
result.frontMatter.pagination_prev = null;
result.frontMatter.pagination_next = null;
}
// 다른 시스템에서 가져온 지원되지 않는 프런트 매터 항목의 이름 변경
if (result.frontMatter.cms_seo_summary) {
result.frontMatter.description = result.frontMatter.cms_seo_summary;
delete result.frontMatter.cms_seo_summary;
}
return result;
},
},
};
인용 단락
Markdown 인용 단락에는 아름다운 스타일이 적용됩니다:
> 유지보수가 쉬운 오픈 소스 문서 웹사이트.
>
> — 도큐사우루스
유지보수가 쉬운 오픈 소스 문서 웹사이트.
— 도큐사우루스
접기/펼치기
Markdown에는 HTML 요소를 삽입할 수 있으며, details HTML 요소에는 보기 좋은 스타일이 적용됩니다:
### details 요소 예제
<details>
<summary>접거나 펼쳐 보세요!</summary>
상세 내용입니다
```js
console.log("코드 블록을 비롯한 Markdown 기능을 사용할 수 있습니다");
```
여기서는 **굵게**나 _기울임꼴_ 서식, [인라인 링크](https://docusaurus.io) 등 Markdown 기능을 사용할 수 있습니다
<details>
<summary>중첩된 접기/펼치기! 안에 깜짝 놀랄 내용이 있어요...</summary>
😲😲😲😲😲
</details>
</details>
details 요소 예제
접거나 펼쳐 보세요!
상세 내용입니다
console.log("코드 블록을 비롯한 Markdown 기능을 사용할 수 있습니다");
여기서는 굵게나 기울임꼴 서식, 인라인 링크 등 Markdown 기능을 사용할 수 있습니다 😲😲😲😲😲중첩된 접기/펼치기! 안에 깜짝 놀랄 내용이 있어요...
\<summary>는 한 줄로 작성하는 것이 좋습니다. MDX는 줄바꿈이 있으면 HTML \<p> 문단을 추가로 생성합니다. 이 점을 기억하세요. 확실하지 않다면 MDX 플레이그라운드를 사용해 \<details> 렌더링 문제를 해결해 보세요.