마크다운에 리액트 컴포넌트 삽입: unified와 MDX 활용법

기술 블로그에서 마크다운의 기본 문법을 넘어 더 풍부한 시각적 효과를 구현하기 위해, 마크다운 파일 내 커스텀 태그를 리액트 컴포넌트로 변환하는 방법을 다룬다. 특히 Gatsby 환경에서 unified 라이브러리를 활용해 마크다운을 HTML로 변환하는 과정을 이해하고, 이를 역이용해 HTML을 다시 리액트 트리로 변환하는 방식을 제시한다.

마크다운에서 HTML로의 변환 과정

마크다운을 HTML로 변환하는 핵심은 unified 라이브러리를 사용하는 것이다. 이 과정은 세 단계로 나뉘며, 각 단계에서 추상 구문 트리(AST)를 거친다.

1. Markdown to mdast: remark-parse를 사용해 마크다운 텍스트를 mdast(Markdown Abstract Syntax Tree)로 변환한다.
2. mdast to hast: remark-rehype를 통해 mdast를 hast(Hypertext Abstract Syntax Tree)로 변환한다. 이 과정에서 heading 타입은 h2 태그로, emphasis는 em 태그로 변경되는 등 HTML 구조에 맞는 노드 타입으로 바뀐다.
3. hast to HTML: rehype-stringify를 이용해 hast를 최종 HTML 문자열로 조립한다.

Gatsby에서 리액트 컴포넌트 삽입하기

Gatsby는 내부적으로 마크다운을 HTML로 변환하므로, 변환 과정에 직접 개입하기 어렵다. 따라서 Gatsby가 생성한 HTML을 다시 파싱하여 리액트 컴포넌트로 치환하는 방식을 사용한다.

• rehype-parse: HTML 문자열을 hast로 변환한다.
• rehype-react: hast를 리액트 요소로 변환하며, components 옵션을 통해 특정 태그명(예: split-diff)을 지정된 리액트 컴포넌트와 매핑한다.
• 이를 통해 마크다운에 작성한 <split-diff>와 같은 커스텀 태그가 렌더링 시 실제 리액트 컴포넌트로 대체되어 동작한다.

MDX를 활용한 대안

더 간단한 방법으로는 MDX를 사용하는 것이 있다. MDX는 마크다운 내에서 JSX를 직접 사용할 수 있게 해주는 형식으로, .mdx 확장자를 사용한다.

• MDX는 작성된 내용을 JavaScript로 컴파일하고 런타임에 실행하는 방식으로 작동한다.
• React 외에도 Preact, Vue 등 JSX를 지원하는 다양한 프레임워크와 호환된다.
• Next.js나 Gatsby에서는 각각 @next/mdx, gatsby-plugin-mdx 플러그인을 설치하여 연동할 수 있다.