마크다운과 JSX를 합친다면?

정현·2025년 3월 16일

MDX

본 글은 잘못된 정보가 포함될 수 있습니다

피드백은 언제나 환영입니다

마크다운 + JSX

요새 마크다운 문법은 정말 많은 곳에 이용된다
지금 이 글을 작성하는 velog도 마크다운 형식으로 작성되고 있다

그런데 이런 편리한 마크다운을 JSX와 합칠 수 있다면?
블로그, 문서 사이트, 정적 웹사이트에 매우 유용할 것이다

Markdown for JSX

그게 바로 Markdown for JSX, MDX다
MDX는 마크다운과 JSX(React 컴포넌트)를 함께 사용할 수 있는 문서 형식이다
즉, 일반적인 마크다운 문법을 사용하면서도, 필요한 부분에 React 컴포넌트를 삽입할 수 있다

사용 준비

react 기준인데 어차피 다 비슷비슷합니다

mdx 파일을 읽어들이고 렌더링해야 하기에 몇가지 준비사항들이 있다

config-overrides.js

const { override, addWebpackModuleRule } = require('customize-cra');

module.exports = override(
  addWebpackModuleRule({
    test: /\.mdx$/,  // MDX 파일을 찾기
    use: [
      {
        loader: 'babel-loader',
      },
      {
        loader: '@mdx-js/loader', // MDX를 React 컴포넌트로 변환해줌
      },
    ],
  })
);

package.json

"scripts": {
    "start": "react-app-rewired start",
    "build": "react-app-rewired build",
    "test": "react-app-rewired test"
  },

라이브러리 설치

yarn add react-app-rewired --dev
yarn add @mdx-js/loader
yarn add @mdx-js/react

뭐 이정도가 있겠다
사실 나도 처음에 공식에서 시키는대로 했다가 에러가 조금 났어서 추가적으로 찾아본거라 정확한게 아닐 수도 있음

그럼 사용해보자


import { MDXProvider } from "@mdx-js/react";

const CustomH1 = (props) => <h1 style={{ color: "red" }} {...props} />;

const components = {
  h1: CustomH1, // MDX의 #이 CustomH1 컴포넌트 형태로 렌더링되는거임
};

export default function 예시({ children }) {
  return <MDXProvider components={components}>{children}</MDXProvider>;
}

위에처럼 사용하면 되겠다
MDXProvider로 일단 감싸고, components에 사용할 컴포넌트들을 집어 넣어주면 된다

위에 예시에서는 H1 태그 즉, #으로 입력했을때를 다음과 같이 스타일을 지정해주는 방법이다

import MainDocs from '../../components/main/mainDocs.mdx';

<MDXProvider components={{}}>
	<Docs>
		<MainDocs></MainDocs>
	</Docs>       
</MDXProvider>

컴포넌트를 이용하지 않을거라면 그냥 컴포넌트를 비워놓아도 괜찮다

장점

이걸 썼을때의 장점이 있어야 쓰는 이유가 있겠죠?

문서 수정이 필요없거나 자주 일어나지 않고, 마크다운을 쓸거라면 나쁘지 않은 선택지라고 생각한다
마크다운에서 컴포넌트를 활용할 수 있다
JSX와 결합한 형태다 보니 미리 선언해준 컴포넌트들을 마크다운과 함께 사용할 수 있다는 것은 분명한 장점일 것이다
그렇기에 재사용은 물론 버튼,차트 같은 것도 넣기 더 편리할 것이다
개발자 친화적이며, 스타일링까지 자유롭다
마크다운만 사용하면 스타일링이 제한되는 경우가 많지만 mdx를 사용한다면 조금 더 자유로울 것이다