메인 컨텐츠로 이동
Version: 2.0.0-beta.9

MDX와 리액트

마크다운에서 JSX 사용하기

도큐사우루스는 MDX v1를 기본 지원합니다. MDX를 기반으로 마크다운 파일 내에 JSX를 작성해서 리액트 컴포넌트를 표현할 수 있습니다.

note

.md 또는 .mdx 확장자를 가진 파일은 모두 MDX에 의해 구문이 해석됩니다. 일부 문법은 약간 다르게 처리될 수 있습니다. 좀 더 정확한 구문 해석과 에디터 지원을 위해 MDX 문법을 포함한 .mdx 파일 확장자를 사용하는 것을 권장합니다.

caution

MDX는 CommonMark와 100% 호환을 보장하지는 않습니다.

MDX playground에서 여러분이 사용하는 문법이 유효한 MDX 구문인지 확인해보세요.

아래 코드를 실행해보세요.

export const Highlight = ({children, color}) => (
<span
style={{
backgroundColor: color,
borderRadius: '2px',
color: '#fff',
padding: '0.2rem',
}}>
{children}
</span>
);

<Highlight color="#25c2a0">도큐사우루스 초록</Highlight><Highlight color="#1877F2">페이스북 파랑</Highlight>은 내가 좋아하는 색입니다.

**마크다운**을 _JSX_와 같이 사용할 수 있습니다!

리액트 컴포넌트와 마크다운 문법이 어떻게 마크업 코드로 변환되는지 확인할 수 있습니다.

http://localhost:3000
도큐사우르스 초록 페이스북 파랑은 내가 좋아하는 색입니다.

마크다운JSX와 같이 사용할 수 있습니다!


다른 파일에 설정한 사용자 지정 컴포넌트나 npm으로 설치한 서드파티 컴포넌트를 가져올 수도 있습니다. MDX 문서에서 MDX로 할 수 있는 더 많은 흥미로운 기능을 찾아볼 수 있습니다.

caution

모든 문서 파일은 MDX에서 구문을 해석하지만 일부 HTML은 JSX에서 처리합니다. 그래서 컴포넌트를 인라인 스타일로 설정해야 하는 경우 JSX 형식을 따르며 style 오브젝트를 지정해주어야 합니다. 이 부분은 도큐사우루스 1과 달라진 점입니다. 자세한 내용은 v1에서 v2로 이전하기를 참고하세요.

코드 스니펫 가져오기

Webpack raw-loader 덕분에 컴포넌트 정의가 포함된 파일을 가져올 수 있을 뿐 아니라 모든 코드 파일을 텍스트 형태로 가져와서 코드 블록에 삽입할 수 있습니다. raw-loader를 사용하기 위해서 먼저 여러분의 프로젝트에 설치해주어야 합니다.

npm install --save raw-loader

이제 아래와 같은 형태로 다른 파일에서 코드 스니펫을 가져올 수 있습니다.

myMarkdownFile.mdx
import CodeBlock from '@theme/CodeBlock';
import MyComponentSource from '!!raw-loader!./myComponent';

<CodeBlock className="language-jsx">{MyComponentSource}</CodeBlock>
http://localhost:3000
/**
* Copyright (c) Facebook, Inc. and its affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/

import React, {useState} from 'react';

export default function MyComponent() {
const [bool, setBool] = useState(false);
return (
<div>
<p>MyComponent rendered !</p>
<p>bool={bool ? 'true' : 'false'}</p>
<p>
<button onClick={() => setBool((b) => !b)}>toggle bool</button>
</p>
</div>
);
}

CodeBlock 컴포넌트에 title 속성을 설정해서 코드 블록 위에 제목처럼 보이게 할 수 있습니다.

<CodeBlock className="language-jsx" title="/src/myComponent">
{MyComponentSource}
</CodeBlock>
note

마크다운에서 3개의 억음부호``` 대신 <CodeBlock>을 사용해야 합니다. 억음부호를 사용하면 그 내용을 그대로 보여주는데 우리는 가져온 텍스트를 JSX에서 삽입하기를 원하기 때문입니다.

warning

이 기능은 아직 실험중이며 향후 API 변경 사항이 적용될 수 있습니다.

마크다운 가져오기

마크다운 파일을 컴포넌트처럼 사용할 수 있습니다. 마크다운 파일 또는 리액트 페이지로 가져오기를 할 수 있습니다.

규칙에 따라 _ 파일명 접두사를 사용할 때 문서 페이지가 생성되지 않는다면 마크다운 파일이 다른 파일에서 가져온 "일부분"임을 의미합니다.

_markdown-partial-example.mdx
<span>Hello {props.name}</span>

This is text some content from `_markdown-partial-example.mdx`.
someOtherDoc.mdx
import PartialExample from './_markdown-partial-example.mdx';

<PartialExample name="Sebastien" />;
http://localhost:3000
안녕하세요 Sebastien

_markdown-partial-example.md에서 가져온 텍스트입니다.


이렇게 하면 여러 페이지에서 콘텐츠를 재사용할 수 있으며 자료의 중복을 방지할 수 있습니다.

caution

현재는 가져온 마크다운 파일의 제목이 목차에 포함되지 않습니다. 기술적인 제약이며 해결하기 위해 노력하고 있습니다(관련 이슈를 참고하세요).