기술 블로그는 엔지니어에게 지식 공유와 개인 브랜딩의 중요한 도구이다. 나 또한 그 필요성을 느끼며 여러 플랫폼을 검토했다. 기존의 복잡한 CMS나 제약이 많은 플랫폼 대신, 직접 제어할 수 있는 유연하고 고성능의 블로그 시스템 구축을 목표로 했다. 그 과정에서 Astro와 MDX의 조합이 탁월한 선택지임을 알게 되었고, 이번 시리즈를 통해 그 구축 과정을 공유하고자 한다.
이 글은 Astro와 MDX를 활용한 기술 블로그 구축 시리즈의 첫 번째 편으로, 개발 환경 설정 및 기본적인 프로젝트 초기화 방법을 다룬다.
1. 왜 Astro와 MDX인가?
기술 블로그는 단순히 글을 쓰는 공간을 넘어, 코드 스니펫, 다이어그램, 상호작용 가능한 데모 등 다양한 콘텐츠를 효과적으로 전달해야 한다. 기존 마크다운의 한계를 극복하고, 웹 성능까지 고려해야 했다.
Astro: Astro는 “Islands architecture”를 기반으로 하는 최신 웹 프레임워크이다. 기본적으로 정적 HTML을 생성하여 로드 시간이 매우 빠르고, 필요한 인터랙티브 컴포넌트만 클라이언트 사이드 JavaScript로 하이드레이션하여 불필요한 JS 로드를 최소화한다. 이는 SEO 측면에서도 유리하며, 사용자 경험을 크게 향상시킨다. React, Vue, Svelte 등 다양한 UI 프레임워크를 지원하여 유연한 컴포넌트 개발이 가능하다는 장점이 있다.
MDX: MDX는 마크다운(Markdown) 내에서 JSX를 사용할 수 있게 해주는 강력한 확장이다. 즉, 평범한 마크다운 문서 안에 React, Vue, Svelte 컴포넌트 등을 삽입할 수 있다는 의미이다. 이를 통해 복잡한 코드 블록, 임베디드 다이어그램, 대화형 예제 등을 마크다운의 간결함과 컴포넌트의 풍부한 기능을 결합하여 작성할 수 있게 된다. 이는 기술 블로그에서 정보를 시각적이고 동적으로 전달하는 데 매우 효과적이다.
2. 개발 환경 설정
Astro 프로젝트를 시작하기 전에 Node.js 환경이 필요하다. 대부분의 개발자에게 익숙하겠지만, 혹시 설치되어 있지 않다면 먼저 Node.js 공식 웹사이트에서 LTS 버전을 설치해야 한다.
2.1. Astro 프로젝트 초기화
터미널을 열고 다음 명령어를 입력하여 새로운 Astro 프로젝트를 생성한다:
npm create astro@latest
이 명령어는 몇 가지 질문을 할 것이다.
Where should we create your new project?: 원하는 프로젝트 디렉토리 이름 (예:devbj-techlog)How would you like to start your new project?:Blog템플릿을 선택하거나Empty로 시작하여 직접 구성할 수 있다. 블로그를 만드는 목적이므로Blog템플릿을 선택하는 것이 편리하다.Install dependencies?:Yes를 선택하여 필요한 의존성을 설치한다.Do you plan to write TypeScript?: 필요에 따라Yes또는No를 선택한다. (Strict를 선택하는 것을 권장한다.)Initialize a new git repository?:Yes를 선택하여 Git 레포지토리를 초기화한다.
프로젝트 생성이 완료되면, 생성된 디렉토리로 이동한다:
cd devbj-techlog
2.2. MDX 통합
Astro는 MDX를 기본적으로 지원하지 않으므로, MDX를 사용하기 위한 인테그레이션을 추가해야 한다. 프로젝트 디렉토리 내에서 다음 명령어를 실행한다:
npx astro add mdx
이 명령어는 @astrojs/mdx 패키지를 설치하고, astro.config.mjs 파일에 MDX 인테그레이션을 자동으로 추가한다. astro.config.mjs 파일은 다음과 유사하게 업데이트될 것이다.
// astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx'; // MDX 인테그레이션
// https://astro.build/config
export default defineConfig({
integrations: [mdx()] // 여기에 추가됨
});2.3. 개발 서버 실행
이제 모든 설정이 완료되었다. 개발 서버를 시작하여 Astro 블로그가 제대로 작동하는지 확인해 볼 수 있다.
npm run dev
이 명령어를 실행하면 로컬 개발 서버가 시작되고, 보통 http://localhost:4321 주소에서 블로그에 접속할 수 있다. 기본 Blog 템플릿을 선택했다면, 미리 작성된 예시 게시물과 함께 블로그 레이아웃을 확인할 수 있을 것이다.
3. 프로젝트 기본 구조 (Blog 템플릿 기준)
Astro Blog 템플릿으로 프로젝트를 초기화했다면, 다음과 같은 핵심 디렉토리 구조를 가지게 된다.
* `src/`: 프로젝트의 모든 소스 코드가 위치하는 곳
* `components/`: 재사용 가능한 Astro, React, Vue 등의 UI 컴포넌트
* `content/`: 블로그 게시물, 페이지 등 MDX 또는 마크다운 파일 (`.mdx`, `.md`)
* `blog/`: 개별 블로그 게시물 파일
* `layouts/`: 페이지 레이아웃 컴포넌트 (예: `BaseLayout.astro`)
* `pages/`: 라우팅되는 페이지 파일 (예: `index.astro`, `blog.astro`)
* `styles/`: 전역 스타일시트
* `public/`: 정적으로 제공될 파일들 (이미지, 폰트 등)
* `astro.config.mjs`: Astro 설정 파일
* `package.json`: 프로젝트 의존성 및 스크립트 정의src/content/blog 디렉토리에 .md 또는 .mdx 확장자를 가진 파일을 생성하면, Astro가 이를 자동으로 감지하여 블로그 게시물로 처리한다. MDX 파일을 작성할 때는 상단에 YAML 프론트매터(Frontmatter)를 추가하여 제목, 작성일, 태그 등의 메타데이터를 정의할 수 있다.
---
title: "나의 첫 MDX 게시물"
pubDatetime: 2026-03-30T10:00:00Z
description: "MDX로 작성된 첫 번째 블로그 게시물입니다."
tags: ["MDX", "Astro", "Tutorial"]
---
이것은 **MDX** 파일입니다.
console.log("마크다운 안에 코드 블록도 가능!");
이제 여기에 React 컴포넌트도 삽입할 수 있습니다!
import MyButton from '../components/MyButton.astro';
<MyButton text="클릭하세요" />물론 위 예시에서 MyButton 컴포넌트는 src/components/MyButton.astro 경로에 실제 컴포넌트 파일이 존재해야 정상적으로 렌더링된다.
4. 마무리
이번 편에서는 Astro와 MDX를 활용한 기술 블로그 구축을 위한 기본적인 개발 환경 설정과 프로젝트 초기화 과정을 살펴보았다. MDX를 통해 마크다운의 간결함과 JSX의 유연성을 동시에 확보할 수 있었고, Astro의 고성능 아키텍처는 블로그의 빠른 로드 속도를 보장한다.
다음 편에서는 실제 블로그 게시물 작성 방법, 이미지 최적화, 그리고 커스텀 컴포넌트 생성 및 활용 방법에 대해 더 자세히 다룰 예정이다.
DevBJ | No Bio, Just Log 기술 삽질로그