@astrojs/ mdx

이 Astro 통합 을 통해 MDX 컴포넌트를 사용할 수 있으며 페이지를 .mdx 파일로 생성할 수 있습니다.

왜 MDX인가?

MDX를 사용하면 Astro에서 Markdown 콘텐츠 내에서 변수, JSX 표현식 및 컴포넌트를 사용할 수 있습니다. MDX로 작성된 기존 콘텐츠가 있는 경우 이 통합을 통해 해당 파일을 Astro 프로젝트로 가져올 수 있습니다.

설치

Astro에는 공식 통합 설정을 자동화하는 astro add 명령이 포함되어 있습니다. 원하는 경우 대신 통합을 수동으로 설치할 수 있습니다.

새 터미널 창에서 다음 명령 중 하나를 실행합니다.

npx astro add mdx

pnpm astro add mdx

yarn astro add mdx

문제가 발생하면 GitHub에서 언제든지 보고하고 아래 수동 설치 단계를 시도해 보세요.

수동 설치

먼저 @astrojs/mdx 패키지를 설치하세요.

npm install @astrojs/mdx

pnpm add @astrojs/mdx

yarn add @astrojs/mdx

그런 다음 integrations 속성을 사용하여 astro.config.* 파일에 통합을 적용합니다.

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [mdx()],
});

편집기 통합

VS Code에서 편집기를 지원하려면 공식 MDX 확장 프로그램을 설치하세요.

다른 편집기의 경우 MDX 언어 서버를 사용하세요.

사용하기

표준 MDX 기능 사용에 대해 알아보려면 MDX 문서를 참조하세요.

Astro의 MDX

MDX 통합을 추가하면 JSX 변수, 표현식, 컴포넌트로 Markdown을 작성하는 기능이 향상됩니다.

또한 MDX에서 Markdown 스타일의 프런트매터를 지원하는 등 표준 MDX에 기능이 추가됩니다. 이를 통해 대부분의 Astro에 내장된 Markdown 기능을 사용할 수 있습니다.

.mdx 파일은 Astro의 HTML과 유사한 구문이 아닌 MDX 구문으로 작성해야 합니다.

내보낸 변수를 MDX에서 사용하기

MDX는 export 문을 사용하여 MDX 콘텐츠에 변수를 추가하거나 이를 가져오는 컴포넌트로 데이터를 내보내는 기능을 지원합니다.

예를 들어, MDX 페이지 또는 컴포넌트에서 {JSX 표현식}을 제목으로 사용할 title 필드를 내보낼 수 있습니다:

export const title = 'My first MDX post'

# {title}

또는 import 및 import.meta.glob() 문을 사용하여, 내보낸 title을 페이지에서 사용할 수 있습니다:

---
const matches = await import.meta.glob('./posts/*.mdx', { eager: true });
const posts = Object.values(posts);
---

{posts.map(post => <p>{post.title}</p>)}

내보낸 속성

import 문 또는 import.meta.glob()을 사용할 때, .astro 컴포넌트에서 사용할 수 있는 속성은 다음과 같습니다:

file - 파일의 절대 경로 (예: /home/user/projects/.../file.mdx).
url - 페이지의 URL (예: /en/guides/markdown-content).
frontmatter - 파일의 YAML 프런트매터에 지정된 모든 데이터를 포함합니다.
getHeadings() - 파일에 있는 모든 제목 (<h1>에서 <h6>)의 배열 (타입은 { depth: number; slug: string; text: string }[])을 반환하는 비동기 함수입니다. 각 제목의 slug는 주어진 제목에 대해 생성된 ID에 해당하며 링크로 사용될 수 있습니다.
<Content /> - 파일의 렌더링된 전체 콘텐츠를 반환하는 컴포넌트입니다.
(모든 export 값) - MDX 파일은 export 문을 사용하여 데이터를 내보낼 수도 있습니다.

MDX에서 프런트매터 변수 사용

기본적으로 Astro MDX 통합은 MDX에서 프런트매터를 사용하는 것을 지원합니다. Markdown 파일과 마찬가지로 프런트매터 속성을 추가하면 이러한 변수를 템플릿에서 사용할 수 있으며, 다른 곳에서 파일을 가져올 때 명명된 속성으로도 사용할 수 있습니다.

---
layout: '../../layouts/BlogPostLayout.astro'
title: 'My first MDX post'
---

# {frontmatter.title}

MDX에서 컴포넌트 사용

MDX 통합을 설치한 후에는 다른 Astro 컴포넌트에서 사용하는 것과 마찬가지로 MDX (.mdx) 파일에서 Astro 컴포넌트와 UI 프레임워크 컴포넌트 모두를 가져와서 사용할 수 있습니다.

필요한 경우 UI 프레임워크 컴포넌트에 client:지시어를 포함시키는 것을 잊지 마세요!

가져오기 및 내보내기 문 사용에 대한 자세한 예는 MDX 문서를 참조하세요.

---
layout: ../layouts/BaseLayout.astro
title: About me
---
import Button from '../components/Button.astro';
import ReactCounter from '../components/ReactCounter.jsx';

I live on **Mars** but feel free to <Button title="Contact me" />.

Here is my counter component, working in MDX:

<ReactCounter client:load />

가져온 MDX를 사용하는 사용자 정의 컴포넌트

가져온 MDX 콘텐츠를 렌더링할 때 사용자 정의 컴포넌트는 components 속성을 통해 전달될 수 있습니다.

---
import { Content, components } from '../content.mdx';
import Heading from '../Heading.astro';
---
<!-- # 구문에 대한 사용자 정의 <h1>을 생성합니다. _그리고_ `content.mdx`에 정의된 모든 사용자 정의 컴포넌트에 적용합니다. -->
<Content components={{...components, h1: Heading }} />

HTML 요소에 사용자 정의 컴포넌트 할당

MDX를 사용하면 표준 HTML 요소 대신 Markdown 구문을 사용자 정의 컴포넌트에 매핑할 수 있습니다. 이렇게 하면 표준 Markdown 구문으로 작성하되 선택한 요소에 특별한 컴포넌트 스타일을 적용할 수 있습니다.

사용자 정의 컴포넌트를 .mdx 파일로 가져온 다음 표준 HTML 요소를 사용자 정의 컴포넌트에 매핑하는 components 객체를 내보냅니다:

import Blockquote from '../components/Blockquote.astro';
export const components = {blockquote: Blockquote}

> This quote will be a custom Blockquote

---
const props = Astro.props;
---
<blockquote {...props} class="bg-blue-50 p-4">
  <span class="text-4xl text-blue-600 mb-2">“</span>
  <slot /> <!-- 하위 콘텐츠를 위해 `<slot/>`을 추가해야 합니다! -->
</blockquote>

사용자 정의 컴포넌트로 덮어쓸 수 있는 HTML 요소의 전체 목록은 MDX 웹사이트를 참조하세요.

구성

MDX 통합이 설치되면 Astro 프로젝트에서 .mdx 파일을 사용하기 위해 구성할 필요가 없습니다.

다음 옵션을 사용하여 MDX가 렌더링되는 방식을 구성할 수 있습니다.

Markdown 구성에서 상속된 옵션
extendMarkdownConfig
recmaPlugins
optimize

Markdown 구성에서 상속된 옵션

모든 markdown 구성 옵션은 MDX 통합에서 별도로 구성할 수 있습니다. 여기에는 remark 및 rehype 플러그인, 구문 강조 등이 포함됩니다. 옵션은 기본적으로 Markdown 구성의 옵션으로 설정됩니다 (이를 수정하려면 extendMarkdownConfig 옵션 참조).

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import remarkToc from 'remark-toc';
import rehypePresetMinify from 'rehype-preset-minify';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      syntaxHighlight: 'shiki',
      shikiConfig: { theme: 'dracula' },
      remarkPlugins: [remarkToc],
      rehypePlugins: [rehypePresetMinify],
      remarkRehype: { footnoteLabel: 'Footnotes' },
      gfm: false,
    }),
  ],
});

전체 옵션 목록은 Markdown 옵션 참조를 확인하세요.

`extendMarkdownConfig`

타입: boolean
기본값: true

MDX는 기본적으로 프로젝트의 기존 Markdown 구성을 확장합니다. 개별 옵션을 재정의하려면 MDX 구성에서 해당 옵션을 지정하면 됩니다.

예를 들어 GitHub 기반 Markdown을 비활성화하고 MDX 파일에 대해 다른 remark 플러그인 세트를 적용해야 한다고 가정해 보겠습니다. 기본적으로 extendMarkdownConfig가 활성화된 상태에서 이러한 옵션을 다음과 같이 적용할 수 있습니다.

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  markdown: {
    syntaxHighlight: 'prism',
    remarkPlugins: [remarkPlugin1],
    gfm: true,
  },
  integrations: [
    mdx({
      // Markdown에서 상속된 `syntaxHighlight`

      // 마크다운 `remarkPlugins`가 무시되었습니다.
      // `remarkPlugin2`만 적용되었습니다.
      remarkPlugins: [remarkPlugin2],
      // `gfm`이 `false`로 재정의되었습니다.
      gfm: false,
    }),
  ],
});

MDX에서 markdown 구성 확장을 비활성화해야 할 수도 있습니다. 이를 위해 extendMarkdownConfig를 false로 설정하세요.

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  markdown: {
    remarkPlugins: [remarkPlugin1],
  },
  integrations: [
    mdx({
      // markdown 구성은 이제 무시됩니다.
      extendMarkdownConfig: false,
      // 'remarkPlugins'가 적용되지 않았습니다.
    }),
  ],
});

`recmaPlugins`

출력되는 estree를 직접 수정하는 플러그인입니다. 이는 MDX 파일에서 JavaScript 변수를 수정하거나 삽입하는 데 유용합니다.

AST Explorer를 사용하여 estree 출력을 수행하고 estree-util-visit를 사용하여 JavaScript 노드를 검색하는 것이 좋습니다.

`optimize`

타입: boolean | { ignoreElementNames?: string[] }

이는 내부 rehype 플러그인을 통해 더 빠른 빌드 및 렌더링을 위해 MDX 출력을 최적화하기 위한 선택적 구성 설정입니다. MDX 파일이 많고 빌드 속도가 느린 경우에 유용할 수 있습니다. 그러나 이 옵션은 일부 이스케이프 처리되지 않은 HTML을 생성할 수 있으므로 활성화한 후에도 사이트의 대화형 부분이 여전히 올바르게 작동하는지 확인하세요.

이는 기본적으로 비활성화되어 있습니다. MDX 최적화를 활성화하려면 MDX 통합 구성에 다음을 추가하십시오.

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      optimize: true,
    }),
  ],
});

`ignoreElementNames`

타입: string[]

Added in: @astrojs/mdx@3.0.0

이전에는 customComponentNames로 알려졌습니다.

MDX 최적화 프로그램이 컴포넌트 prop을 통해 가져온 MDX 콘텐츠에 전달된 사용자 정의 컴포넌트와 같은 특정 요소 이름을 처리하지 못하도록 방지하는 optimize의 선택적 속성입니다.

최적화 프로그램이 콘텐츠를 정적 문자열로 변환하므로 동적으로 렌더링해야 하는 사용자 정의 컴포넌트가 중단되기 때문에 최적화에서 이러한 컴포넌트를 제외해야 합니다.

예를 들어 다음 의도된 MDX 출력은 모두 "<h1>...</h1>"이 아닌 <Heading>...</Heading>입니다.

---
import { Content, components } from '../content.mdx';
import Heading from '../Heading.astro';
---

<Content components={{ ...components, h1: Heading }} />

ignoreElementNames 속성을 사용하여 이에 대한 최적화를 구성하려면 맞춤 컴포넌트로 처리되어야 하는 HTML 요소 이름의 배열을 지정하세요.

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      optimize: {
        // 최적화 프로그램이 'h1' 요소를 처리하지 못하도록 방지
        ignoreElementNames: ['h1'],
      },
    }),
  ],
});