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

MDX and React

마크다운에서 JSX 사용하기#

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

note

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

caution

MDX is not 100% compatible with CommonMark.

Use the MDX playground to ensure that your syntax is valid 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 덕분에 컴포넌트 정의가 포함된 파일을 가져올 수 있을 뿐 아니라 모든 코드 파일을 텍스트 형태로 가져와서 코드 블록에 삽입할 수 있습니다. In order to use raw-loader, first you need to install it in your project:

npm install --save raw-loader

Now you can import code snippets from another file as it is:

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>  );}

You can also pass title prop to CodeBlock component in order to appear it as header above your codeblock:

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

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

warning

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

마크다운 가져오기#

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

By convention, using the _ filename prefix will not create any doc page and means the markdown file is a "partial", to be imported by other files.

_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
Hello Sebastien

This is text some content from _markdown-partial-example.md.


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

caution

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