Version: 2.0.0-beta.3

리액트 사용하기

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

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

note

.md 또는 .mdx 확장자를 가진 파일은 모두 MDX에 의해 구문이 해석됩니다. 일부 문법은 약간 다르게 처리될 수 있습니다. 좀 더 정확한 구문 해석과 에디터 지원을 위해 MDX 문법을 포함한 .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 덕분에 컴포넌트 정의가 포함된 파일을 가져올 수 있을 뿐 아니라 모든 코드 파일을 텍스트 형태로 가져와서 코드 블록에 삽입할 수 있습니다.

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

note

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

warning

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

마크다운 가져오기#

마크다운 파일을 컴포넌트처럼 사용할 수 있습니다. 마크다운 파일 또는 리액트 페이지로 가져오기를 할 수 있습니다. 아래 예는 다른 마크다운 파일을 가져와서 컴포넌트처럼 삽입했습니다.

import Intro from './markdown-features-intro.mdx';
<Intro />;

http://localhost:3000

문서는 사용자가 만날 수 있는 제품 접점 중 하나입니다. 적절하게 구성되고 쓰인 문서는 사용자가 제품을 빠르게 이해하는 데 도움을 줍니다. 우리의 목표는 여러분의 사용자가 가능한 한 빨리 필요한 정보를 찾고 이해할 수 있도록 도와주는 것입니다.

도큐사우루스 2는 여러분이 문서를 쉽게 작성할 수 있도록 최신의 도구를 사용하고 있습니다. 리액트 컴포넌트를 활용하거나 라이브 코딩 블록을 사용해 사용자가 코드 실행 결과를 바로 확인할 수 있도록 문서를 작성할 수 있습니다. 문서에서 벗어나지 않고 떠오른 아이디어를 코드로 확인해볼 수 있습니다. 이런 방식은 잠재적인 사용자에게 흥미를 주는 가장 효과적인 방법입니다.

이번 세션에서는 여러분이 문서 작성 시 든든한 도움이 될 수 있는 도구를 소개하려고 합니다. 예를 들면 이런 것입니다.

마크다운은 가독성있는 문법을 사용해 정형화된 콘텐츠를 작성할 수 있습니다.

우리는 기본 마크다운 문법을 지원하고 있으며 MDX를 사용해 마크다운과 리액트 컴포넌트를 같이 해석하고 문서로 표현해줍니다.

important

이번 세션에서는 기본으로 제공되는 도큐사우루스 콘텐츠 플러그인을 사용하고 있다고 가정합니다.

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

caution

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