@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 언어 서버를 사용하세요.

사용하기

Astro MDX 통합을 사용하면 src/pages/ 디렉터리에 .mdx 파일을 추가하여 프로젝트에 MDX 페이지를 추가할 수 있습니다. .mdx 파일을 .astro 파일로 가져올 수도 있습니다.

Astro의 MDX 통합은 Markdown 스타일의 프런트매터를 포함하여 표준 MDX에 기능을 추가합니다. 이를 통해 특별한 프런트매터 layout 속성과 같은 Astro에 내장된 Markdown 기능 대부분을 사용할 수 있습니다.

Markdown 및 MDX 가이드의 예시를 통해 Astro에서 MDX가 어떻게 작동하는지 알아보세요.

표준 MDX 기능 사용에 대해 알아보려면 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 rehypeMinifyHtml from 'rehype-minify-html';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      syntaxHighlight: 'shiki',
      shikiConfig: { theme: 'dracula' },
      remarkPlugins: [remarkToc],
      rehypePlugins: [rehypeMinifyHtml],
      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'],
      },
    }),
  ],
});