Astro Markdown 고급 가이드: 블로그를 10배 더 전문적으로 만드는 7가지 실전 팁

Astro로 블로그를 막 만들고 첫 기술 글을 쓰기 시작했다고 해보겠습니다. 코드의 특정 줄을 강조하고 싶어도 할 수 없고, 독자에게 주의 사항을 알리는 접이식 경고 상자를 넣고 싶어도 방법을 모르겠습니다. 알고리즘 설명에 수학 공식을 추가하는 일은 더 막막합니다.

저도 이런 답답함을 겪었습니다. 순수 Markdown으로 몇 편을 쓰고 나니 표현할 수 있는 범위가 너무 좁다는 사실을 깨달았습니다. 다른 기술 블로그에서는 코드 블록의 핵심을 표시하고 변경 전후를 비교하며 글 안에 인터랙티브 컴포넌트까지 넣는데, 제 글은 코드만 무미건조하게 붙여 놓은 모습이었습니다.

다행히 Astro에는 ‘강화된 Markdown’인 MDX가 있습니다. 간단히 말해 MDX를 사용하면 글을 쓰면서 컴포넌트와 JSX를 쓸 수 있어 표현할 수 있는 범위가 몇 배로 넓어집니다.

이 글에서는 기본 환경 설정부터 코드 하이라이트, 사용자 정의 컴포넌트, 수학 공식, 순서도까지 Astro Markdown/MDX의 고급 활용법 7가지를 소개합니다. 각 팁에는 완전한 코드와 설정 절차를 담았습니다. 끝까지 읽으면 기술 블로그를 ‘읽을 만한 수준’에서 ‘전문적인 수준’으로 끌어올릴 수 있습니다.

1부: 기본 업그레이드 - Markdown에서 MDX로

MDX를 사용해야 하는 이유

Markdown과 MDX의 차이는 자전거와 전기자전거의 차이와 비슷합니다. 둘 다 탈 수 있지만 경험은 완전히 다릅니다.

순수 Markdown은 텍스트, 코드 블록, 이미지 같은 정적 콘텐츠만 작성할 수 있습니다. 안내 상자를 넣으려면 HTML을 직접 작성해야 하고, 글 안에 인터랙티브 컴포넌트를 삽입하는 일은 사실상 어렵습니다.

MDX는 다릅니다. ‘Markdown + JSX’를 결합한 형식이므로 다음 작업을 할 수 있습니다.

• 컴포넌트 가져오기 및 사용: .mdx 파일에서 Astro 컴포넌트나 React/Vue 컴포넌트를 직접 import합니다.
• JSX 표현식 작성: 글에서 {variable}로 변수를 삽입하고 반복문과 조건문까지 작성할 수 있습니다.
• 요소 스타일 사용자 정의: 기본 <h1>을 직접 만든 스타일 컴포넌트로 교체할 수 있습니다.

구체적인 예를 보겠습니다. 글에 경고 상자를 넣으려면 순수 Markdown에서는 다음처럼 작성해야 합니다.

<div class="warning">
  <p>주의: 이 작업은 모든 데이터를 삭제합니다!</p>
</div>

MDX에서는 이렇게 쓸 수 있습니다.

import Alert from '@/components/Alert.astro';

<Alert type="warning">
  주의: 이 작업은 모든 데이터를 삭제합니다!
</Alert>

차이가 보이나요? MDX를 사용하면 글쓰기가 ‘코드를 직접 작성하는 일’보다 ‘블록을 조립하는 일’에 가까워집니다.

5분 만에 MDX 환경 설정하기

MDX 설정은 매우 간단하며 세 단계면 끝납니다.

1단계: 통합 패키지 설치

터미널을 열고 Astro 프로젝트에서 다음 명령을 실행합니다.

npx astro add mdx

Astro CLI가 @astrojs/mdx를 설치하고 설정 파일도 자동으로 업데이트합니다. 설정 업데이트와 의존성 설치 여부를 묻는 질문이 나오면 모두 Yes를 선택하면 됩니다.

2단계: 설정 확인

설치 후 astro.config.mjs를 열면 다음 코드가 있어야 합니다.

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

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

자동으로 추가되지 않았다면 직접 넣으면 됩니다.

3단계: MDX 작동 테스트

src/pages/ 또는 src/content/ 디렉터리에 test.mdx 파일을 만듭니다.

---

title: MDX 테스트

---

# MDX 테스트입니다

일반 Markdown 텍스트입니다.

export const greeting = "안녕하세요";

이제 변수를 사용할 수 있습니다: {greeting}!

<div style="padding: 1rem; background: #f0f0f0;">
  JSX 요소입니다
</div>

npm run dev를 실행하고 해당 페이지에 접속합니다. 변수와 JSX 요소가 정상적으로 표시되면 MDX 설정이 완료된 것입니다.

.md 파일과 .mdx 파일 함께 사용하기

MDX 통합을 설치해도 기존 .md 파일은 그대로 작동하므로 걱정할 필요가 없습니다. Astro는 파일 확장자에 따라 처리 방식을 자동으로 선택합니다.

• .md 파일: 표준 Markdown으로 처리
• .mdx 파일: 컴포넌트와 JSX를 지원하는 MDX로 처리

일반 글에는 .md를 사용하고, 컴포넌트가 필요한 글에만 .mdx를 사용하는 방식을 권합니다. 모든 글에 MDX 기능이 필요한 것은 아닙니다.

2부: 고급 코드 하이라이트 기법

코드 하이라이트 테마 설정(Shiki)

Astro는 기본적으로 Shiki로 코드를 하이라이트합니다. 기본 설정도 훌륭하지만, 기본 테마인 github-dark 대신 블로그 스타일에 더 잘 맞는 테마를 쓰고 싶을 수 있습니다.

Shiki와 Prism 중 무엇을 선택해야 할까요?

솔직히 말하면 Shiki를 추천합니다. Astro의 기본 솔루션이며 100개가 넘는 프로그래밍 언어와 테마를 지원하고, 서버에서 렌더링되므로 별도의 JavaScript를 불러올 필요가 없습니다. Prism도 좋지만 CSS 파일을 추가해야 해서 설정이 조금 더 번거롭습니다.

기본 제공 테마 전환

Alibaba Cloud - 개발자 클라우드 1순위, Lighthouse 서버 15% 할인

15% 할인 받기 →광고

astro.config.mjs를 열고 markdown 설정에 shikiConfig를 추가합니다.

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

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    shikiConfig: {
      theme: 'dracula', // 선택 가능: github-dark, nord, monokai, dracula 등
    },
  },
});

Shiki는 매우 많은 테마를 지원합니다. 제가 자주 쓰는 테마는 다음과 같습니다.

• github-dark / github-light - GitHub 스타일
• dracula - 클래식한 보라색과 검은색 조합
• nord - 차분한 북유럽 스타일
• one-dark-pro - VSCode 기본 다크 테마

Shiki 테마 미리보기에서 마음에 드는 테마를 고를 수 있습니다.

라이트/다크 이중 테마 전환 구현

블로그가 라이트 모드와 다크 모드 전환을 지원한다면 Shiki에 두 테마를 설정할 수 있습니다.

markdown: {
  shikiConfig: {
    themes: {
      light: 'github-light',
      dark: 'github-dark',
    },
  },
},

이렇게 설정하면 Shiki가 CSS의 prefers-color-scheme 또는 직접 구현한 테마 전환 로직에 따라 알맞은 코드 하이라이트 테마를 자동으로 적용합니다.

특정 줄과 코드 주석 강조하기

튜토리얼을 쓸 때는 ‘이 줄이 중요합니다’라고 표시하거나 ‘코드에서 무엇이 바뀌었는지’를 보여줘야 할 때가 많습니다. Shiki Transformers로 이런 기능을 구현할 수 있습니다.

핵심 코드 줄 강조

먼저 Shiki transformers를 설치합니다.

npm install shiki

그런 다음 설정에서 transformerNotationHighlight를 활성화합니다.

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

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    shikiConfig: {
      theme: 'github-dark',
      transformers: [transformerNotationHighlight()],
    },
  },
});

이제 코드 블록에서 // [!code highlight] 주석으로 강조할 줄을 표시할 수 있습니다.

```javascript
function hello() {
  console.log('이 줄은 일반 줄입니다');
  console.log('이 줄은 강조됩니다'); // [!code highlight]
}
```

코드 변경 사항 표시(Diff 스타일)

‘변경 전/후’ 코드를 비교할 때는 transformerNotationDiff를 사용할 수 있습니다.

import { transformerNotationDiff, transformerNotationHighlight } from '@shikijs/transformers';

markdown: {
  shikiConfig: {
    theme: 'github-dark',
    transformers: [
      transformerNotationHighlight(),
      transformerNotationDiff(),
    ],
  },
},

사용법은 다음과 같습니다.

```javascript
function calculate(a, b) {
  return a + b; // [!code --]
  return a * b; // [!code ++]
}
```

--가 붙은 줄은 빨간색(삭제), ++가 붙은 줄은 초록색(추가)으로 표시됩니다. 코드 튜토리얼을 쓸 때 매우 유용한 기능입니다.

특정 코드에 초점 맞추기

transformerNotationFocus를 사용하면 나머지 코드는 흐리게 표시하고 강조하려는 부분만 선명하게 만들 수 있습니다.

import { transformerNotationFocus } from '@shikijs/transformers';

// transformers 배열에 추가
transformers: [
  transformerNotationFocus(),
],

// [!code focus]로 표시합니다.

```javascript
function process() {
  console.log('이 줄은 흐리게 표시됩니다');
  console.log('이 줄은 일반 상태로 표시됩니다'); // [!code focus]
  console.log('이 줄도 흐리게 표시됩니다');
}
```

Expressive Code로 업그레이드하기(선택 사항)

Shiki 기능만으로 부족하다면 Expressive Code를 사용해 보세요. 커뮤니티에서 만든 향상된 코드 표시 솔루션으로, 다음 기능을 기본 제공합니다.

• 코드 블록 제목
• 원클릭 복사 버튼
• 줄 번호 표시
• 터미널 창 스타일
• 코드 비교(Side-by-Side)

매우 간단한 설치

npx astro add astro-expressive-code

Astro CLI가 모든 설정을 자동으로 처리합니다. 설치가 끝나면 별도 설정 없이 코드 블록에 해당 기능이 자동으로 추가됩니다.

Expressive Code는 언제 사용해야 할까요?

저도 처음에는 기본 Shiki를 사용했지만, 독자가 코드를 복사하는 경우가 많다는 사실을 알고 Expressive Code로 바꿨습니다. 블로그가 주로 튜토리얼과 코드 공유를 다룬다면 Expressive Code가 독자 경험을 크게 개선합니다.

반면 가끔 코드만 넣는 정도라면 Shiki와 Transformers면 충분합니다. 불필요한 의존성을 늘릴 필요는 없습니다.

3부: 사용자 정의 컴포넌트 삽입

MDX에서 컴포넌트 가져오기 및 사용

MDX의 가장 강력한 기능은 글에서 컴포넌트를 직접 사용할 수 있다는 점입니다. 저는 이 기능을 안내 상자, 코드 비교, 접이식 영역 등에 자주 사용합니다.

경고 상자 컴포넌트 만들기

먼저 src/components/ 디렉터리에 Alert.astro를 만듭니다.

---

interface Props {
  type?: 'info' | 'warning' | 'error';
}

const { type = 'info' } = Astro.props;

const styles = {
  info: 'bg-blue-50 border-blue-200 text-blue-800',
  warning: 'bg-yellow-50 border-yellow-200 text-yellow-800',
  error: 'bg-red-50 border-red-200 text-red-800',
};

---

<div class={`border-l-4 p-4 ${styles[type]}`}>
  <slot />
</div>

MDX 글에서 사용

.mdx 파일에서 컴포넌트를 가져와 사용합니다.

---

title: 나의 기술 글

---

import Alert from '@/components/Alert.astro';

# 글 제목

일반적인 글 내용입니다.

<Alert type="warning">
  주의: 이 명령을 실행하기 전에 데이터를 백업하세요!
</Alert>

<Alert type="info">
  팁: 컴포넌트 안에서도 **Markdown 문법**을 사용할 수 있어 편리합니다.
</Alert>

보시다시피 <Alert> 컴포넌트 안에서도 굵은 글씨나 링크 같은 Markdown 문법을 계속 사용할 수 있으며 MDX가 자동으로 처리합니다.

React/Vue 컴포넌트 사용

MDX는 Astro 컴포넌트뿐 아니라 React, Vue 같은 프레임워크의 컴포넌트도 지원합니다. 단, client: 지시어를 추가해야 합니다.

import Counter from '@/components/Counter.tsx';

<Counter client:load initialCount={0} />

client:load는 페이지가 로드될 때 이 컴포넌트를 클라이언트에서 실행한다는 뜻입니다. 이를 추가하지 않으면 컴포넌트는 서버에서만 렌더링되며 인터랙션이 작동하지 않습니다.

컴포넌트 파일 구성 제안

글에서 자주 사용하는 컴포넌트는 src/components/mdx/ 디렉터리에 모아 두면 관리하기 쉽습니다.

src/
├── components/
│   ├── mdx/
│   │   ├── Alert.astro
│   │   ├── CodeCompare.astro
│   │   ├── Callout.astro
│   │   └── Tabs.astro
│   └── ...기타 컴포넌트

Markdown 문법을 사용자 정의 컴포넌트에 매핑하기

이 기능은 약간의 ‘흑마법’처럼 느껴집니다. h1, a, img 같은 Markdown 기본 요소를 직접 만든 컴포넌트로 바꿀 수 있기 때문입니다.

왜 이렇게 해야 할까요?

예를 들어 모든 제목에 앵커 아이콘을 붙이거나 외부 링크에 ‘↗’ 표시를 자동으로 추가하고 싶을 수 있습니다. 일일이 추가하는 것은 번거롭지만, 컴포넌트 매핑을 사용하면 표준 Markdown만 작성해도 스타일이 자동으로 적용됩니다.

실전: 사용자 정의 제목 컴포넌트

먼저 CustomHeading.astro를 만듭니다.

---

interface Props {
  level: 1 | 2 | 3 | 4 | 5 | 6;
  id?: string;
}

const { level, id } = Astro.props;
const Tag = `h${level}` as any;

---

<Tag id={id} class="group relative">
  <slot />
  {id && (
    <a href={`#${id}`} class="ml-2 opacity-0 group-hover:opacity-100 transition-opacity">
      #
    </a>
  )}
</Tag>

MDX에서 매핑 사용

Railway - 현대적인 배포 플랫폼, 번거로운 운영 없이 몇 분 만에 라이브

지금 시작 →광고

.mdx 파일에서 components 객체를 내보냅니다.

---

title: 글 제목

---

import CustomHeading from '@/components/CustomHeading.astro';

export const components = {
  h2: (props) => <CustomHeading level={2} {...props} />,
  h3: (props) => <CustomHeading level={3} {...props} />,
};

## 2단계 제목입니다

제목 위에 마우스를 올리면 # 앵커 링크가 나타납니다.

### 3단계 제목입니다

모든 h2와 h3에 사용자 정의 스타일이 자동으로 적용됩니다.

실전: 외부 링크에 아이콘 추가

ExternalLink.astro를 만듭니다.

---

interface Props {
  href?: string;
}

const { href } = Astro.props;
const isExternal = href?.startsWith('http');

---

<a href={href} target={isExternal ? '_blank' : undefined} rel={isExternal ? 'noopener noreferrer' : undefined}>
  <slot />
  {isExternal && <span class="ml-1 text-xs">↗</span>}
</a>

매핑은 다음처럼 사용합니다.

import ExternalLink from '@/components/ExternalLink.astro';

export const components = {
  a: ExternalLink,
};

[내부 링크입니다](/about)
[외부 링크입니다](https://example.com) ← ↗ 아이콘이 자동으로 추가됩니다

전역 매핑 설정(고급)

모든 MDX 파일에서 같은 컴포넌트 매핑을 사용하려면 astro.config.mjs에서 설정할 수 있습니다. 다만 사용자 정의 MDX 플러그인이 필요해 조금 복잡하므로, 저는 일반적으로 각 파일에서 설정하는 것으로 충분하다고 봅니다.

4부: 수학 공식과 차트 통합

KaTeX로 수학 공식 표시하기

알고리즘, 수학, 데이터 과학 관련 글을 쓴다면 공식 표시가 반드시 필요합니다. KaTeX는 현재 가장 좋은 선택으로, MathJax보다 훨씬 빠르고 서버 렌더링도 지원합니다.

KaTeX 설치

세 패키지를 설치해야 합니다.

npm install remark-math rehype-katex katex

• remark-math: LaTeX 문법 분석
• rehype-katex: 공식을 HTML로 렌더링
• katex: KaTeX 핵심 라이브러리

Astro 설정

astro.config.mjs를 열고 두 플러그인을 추가합니다.

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    remarkPlugins: [remarkMath],
    rehypePlugins: [rehypeKatex],
  },
});

KaTeX 스타일 가져오기

공식이 올바르게 표시되려면 이 단계가 중요합니다. 레이아웃 파일(예: src/layouts/MarkdownLayout.astro)의 <head>에 다음 코드를 추가합니다.

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css"
  crossorigin="anonymous"
/>

글에서 공식 사용

설정이 끝나면 Markdown/MDX에서 공식을 작성할 수 있습니다.

인라인 공식(단일 $로 감싸기):

질량-에너지 등가식: $E = mc^2$

이차방정식의 해: $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$

블록 공식(이중 $$로 감싸기):

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

자주 발생하는 문제: 공식이 표시되지 않음

공식이 표시되지 않거나 스타일이 올바르지 않다면 다음 사항을 확인하세요.

1. KaTeX CSS를 올바르게 가져왔는지 확인합니다(F12를 눌러 Network 패널 확인).
2. rehype-katex 버전이 호환되는지 확인합니다(6.x 버전으로 낮춰 보세요).
3. 공식 문법이 올바른지 KaTeX 지원 목록에서 확인합니다.

Mermaid로 순서도와 차트 그리기

Mermaid는 코드로 순서도, 시퀀스 다이어그램, 간트 차트 등을 그릴 수 있어 기술 문서에 특히 적합합니다.

세 가지 통합 방식 비교

커뮤니티에는 여러 Mermaid 통합 방식이 있습니다. 차이를 간단히 정리하면 다음과 같습니다.

저는 rehype-mermaid를 추천합니다. 서버에서 렌더링하므로 SEO에 유리하고 정적 SVG를 생성합니다.

rehype-mermaid 설치

npm install rehype-mermaid

설정

astro.config.mjs에 다음 내용을 추가합니다.

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import rehypeMermaid from 'rehype-mermaid';

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    rehypePlugins: [
      [rehypeMermaid, { strategy: 'img-svg' }]
    ],
  },
});

strategy: 'img-svg'는 SVG 이미지를 생성한다는 뜻이며 가장 안정적인 방식입니다.

글에서 다이어그램 그리기

mermaid 코드 블록을 사용하면 됩니다.

순서도 예시:

```mermaid
graph TD
    A[시작] --> B{MDX 설치 여부}
    B -->|예| C[코드 하이라이트 설정]
    B -->|아니요| D[MDX 설치]
    D --> C
    C --> E[완료]
```

시퀀스 다이어그램 예시:

```mermaid
sequenceDiagram
    사용자->>브라우저: 페이지 방문
    브라우저->>서버: HTML 요청
    서버->>브라우저: 렌더링된 페이지 반환
    브라우저->>사용자: 콘텐츠 표시
```

빌드 중 생성

npm run build를 실행하면 Mermaid 차트가 빌드 단계에서 SVG로 생성됩니다. 최종 페이지에는 정적 이미지가 들어가므로 로딩이 빠르고 클라이언트 JavaScript도 필요하지 않습니다.

주의 사항

빌드 중 ‘Puppeteer를 찾을 수 없음’ 오류가 발생하면 추가 설정이 필요할 수 있습니다. playwright를 설치해 보세요.

npm install -D playwright

또는 브라우저 환경이 내장된 astro-diagram 방식을 사용할 수 있습니다.

5부: 고급 팁과 모범 사례

Content Collections의 MDX 최적화

Astro Content Collections로 블로그 글을 관리한다면(강력히 권장합니다) MDX 파일에서 더 나은 타입 지원과 개발 경험을 얻을 수 있습니다.

Vultr - 고성능 NVMe 클라우드 서버, 전 세계 32개 노드, Docker 원클릭 배포

요금 보기 →광고

Content Collections란 무엇인가요?

간단히 말해 글을 src/content/ 디렉터리에 두면 Astro가 frontmatter를 자동으로 인식하고 검증하며, 콘텐츠를 읽기 위한 타입 안전 API를 제공하는 기능입니다.

Content Collections 설정

src/content/config.ts에서 컬렉션을 정의합니다.

import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  type: 'content', // 콘텐츠 파일(Markdown/MDX)임을 나타냅니다
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.date(),
    tags: z.array(z.string()).optional(),
    draft: z.boolean().default(false),
  }),
});

export const collections = { blog };

MDX에서 사용

MDX 파일의 frontmatter는 자동으로 검증됩니다.

---

title: Astro MDX 고급 튜토리얼
description: MDX의 고급 사용법 배우기
pubDate: 2025-12-02
tags: [Astro, MDX, 튜토리얼]

---

import Alert from '@/components/Alert.astro';

# {frontmatter.title}

<Alert type="info">
  게시일: {frontmatter.pubDate.toLocaleDateString()}
</Alert>

목차 자동 생성

Content Collections는 글의 모든 제목을 가져올 수 있는 getHeadings() 메서드를 제공하므로 목차를 만들 수 있습니다.

---

import { getEntry } from 'astro:content';

const entry = await getEntry('blog', 'my-mdx-article');
const { Content, headings } = await entry.render();

---

<aside>
  <h2>목차</h2>
  <ul>
    {headings.map(h => (
      <li style={`margin-left: ${(h.depth - 1) * 1}rem`}>
        <a href={`#${h.slug}`}>{h.text}</a>
      </li>
    ))}
  </ul>
</aside>

<article>
  <Content />
</article>

긴 글을 쓸 때 특히 유용하며 독자가 관심 있는 섹션으로 빠르게 이동할 수 있습니다.

성능 최적화와 흔한 함정

MDX는 강력하지만 잘못 사용하면 사이트가 느려질 수 있습니다. 주의해야 할 몇 가지를 살펴보겠습니다.

클라이언트 컴포넌트 과도하게 사용하지 않기

MDX에서 React/Vue 컴포넌트를 사용할 때는 client:* 지시어를 추가해야 합니다. 지시어가 없으면 컴포넌트가 서버에서만 렌더링되어 인터랙션이 작동하지 않습니다. 반대로 client:load를 남용하면 JavaScript 용량이 크게 늘어나 페이지 로딩이 느려집니다.

권장 방식은 다음과 같습니다.

• 정적 콘텐츠에는 Astro 컴포넌트(Alert, Callout 등)를 사용합니다.
• 인터랙션이 필요한 경우 client:visible(화면에 보일 때 로드) 또는 client:idle(유휴 상태에서 로드)을 사용합니다.
• 꼭 필요한 경우가 아니라면 client:load를 사용하지 않습니다.

이미지 최적화

MDX에서 이미지를 삽입할 때 <img>를 직접 사용하지 말고 Astro의 Image 컴포넌트를 사용합니다.

---

title: 나의 글

---

import { Image } from 'astro:assets';
import cover from './cover.jpg';

<Image src={cover} alt="표지 이미지" width={800} height={600} />

Astro가 이미지 압축, WebP 생성, 지연 로딩 등을 자동으로 처리하므로 성능이 훨씬 좋아집니다.

MDX의 optimize 옵션

사이트에 MDX 파일이 많아 빌드가 느리다면 optimize 옵션을 활성화해 보세요.

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

이 옵션은 내부 rehype 플러그인으로 MDX 출력을 최적화해 빌드 속도를 높입니다. 다만 생성되는 HTML 구조가 바뀔 수 있으므로 사용 전에 테스트해야 합니다.

자주 발생하는 오류와 해결 방법

결론

지금까지 살펴본 핵심 내용을 정리하겠습니다.

7가지 팁 빠르게 복습하기:

1. MDX 환경 설정 - 명령 한 줄로 설정하고 5분 만에 시작합니다.
2. 코드 하이라이트 테마 전환 - Shiki로 원하는 스타일을 설정합니다.
3. 코드 강조 및 주석 표시 - Transformers로 핵심과 변경 사항을 표시합니다.
4. 사용자 정의 컴포넌트 삽입 - Alert부터 인터랙티브 Demo까지 글을 더 생생하게 만듭니다.
5. Markdown 요소 매핑 - 제목과 링크 같은 기본 스타일을 한꺼번에 사용자 정의합니다.
6. 수학 공식 표시 - KaTeX로 알고리즘 설명을 더 전문적으로 만듭니다.
7. 순서도 그리기 - Mermaid로 코드를 사용해 다이어그램을 그리고 서버에서 렌더링합니다.

권장 학습 순서:

모든 기능을 한 번에 배울 필요는 없습니다. 다음 순서를 권합니다.

• 1단계: MDX 환경을 설정하고 간단한 컴포넌트를 하나 가져와 봅니다.
• 2단계: 필요에 따라 코드 하이라이트를 설정합니다(코드가 많은 글이라면 설정하세요).
• 3단계: 알고리즘이나 아키텍처 관련 글을 쓴다면 KaTeX와 Mermaid를 추가합니다.
• 4단계: 익숙해진 뒤 컴포넌트 매핑 같은 ‘흑마법’을 시도합니다.

확인 목록:

설정을 마친 뒤 다음 기능이 정상적으로 작동하는지 확인하세요.

• MDX 파일이 정상적으로 렌더링됨
• 코드 블록에 올바른 하이라이트가 적용됨
• 사용자 정의 컴포넌트가 표시됨
• 수학 공식이 올바르게 렌더링됨(설정한 경우)
• Mermaid 차트가 생성됨(설정한 경우)
• 빌드 속도가 허용 가능한 수준임

다음 단계로 살펴볼 내용:

• Astro Integrations에서 더 흥미로운 플러그인을 찾아봅니다.
• 커뮤니티에서 공유하는 MDX 컴포넌트 라이브러리를 살펴봅니다.
• Astro의 View Transitions로 블로그에 부드러운 페이지 전환 애니메이션을 추가해 봅니다.

이제 가장 관심 있는 기능 하나를 골라 블로그에 적용해 보세요. 설정 중 문제가 생겨도 당황할 필요는 없습니다. 공식 문서와 커뮤니티가 잘 갖춰져 있어 검색하면 대부분 해결 방법을 찾을 수 있습니다.

마지막으로 기술 블로그에서 가장 중요한 것은 여전히 콘텐츠 자체입니다. 이런 도구는 생각을 더 명확하고 전문적으로 표현하도록 도울 뿐이며, 독자를 진정으로 끌어들이는 것은 여러분의 관점과 경험입니다. Astro 블로그가 계속 성장하기를 바랍니다!