MKTGLab

검색어를 입력하면 실시간으로 용어와 글을 찾습니다.

By MKTGLabModern Web Tech8 min read

Astro 5와 Headless WordPress 하이브리드 아키텍처 구축 가이드

로컬 마크다운 파일(Content Collections)과 워드프레스 REST/GraphQL API를 단일 정적 사이트로 통합하여 개발자 경험과 CMS 관리 효율을 동시에 극대화하는 하이브리드 파이프라인 설계 전략을 살펴봅니다.

Updated:

현대 웹 아키텍처에서 콘텐츠 관리 시스템(CMS)과 정적 사이트 생성기(SSG)의 결합은 성능과 사용성의 균형을 잡는 핵심 과제입니다. 비즈니스 마케팅 팀은 워드프레스(WordPress)의 친숙한 위지윅(WYSIWYG) 에디터와 미디어 라이브러리를 선호하지만, 엔지니어링 팀은 Git 기반의 로컬 마크다운(Markdown/MDX) 및 코드 레벨의 정밀한 버전 제어를 원합니다.

이 글에서는 Astro 5의 새로운 콘텐츠 레이어(Content Layer) 와 Headless WordPress를 결합하여, 두 환경의 글을 하나의 통합된 데이터 스트림으로 정규화(Normalize)하고 배포하는 하이브리드 퍼블리싱 아키텍처를 소개합니다.

1. 하이브리드 아키텍처가 필요한 이유

많은 기업과 테크 블로그가 CMS 도입 시 극단적인 양자택일을 경험합니다.

  1. 전통적인 WordPress 단일 환경: 플러그인 호환성과 비개발 직군의 작성 용이성은 높지만, 무거운 PHP 런타임과 복잡한 데이터베이스 쿼리로 인해 코어 웹 바이탈(Core Web Vitals) 점수 확보 및 TTFB(Time to First Byte) 단축에 한계가 발생합니다.
  2. 순수 Git 기반 정적 블로그 (Markdown/MDX): 최고 수준의 페이지 로딩 속도와 빌드 안정성을 제공하지만, 마케터나 기고자가 PR(Pull Request) 생성, Git 커밋, 마크다운 문법을 익혀야 하는 진입 장벽이 존재합니다.

하이브리드 아키텍처는 두 접근법의 장점만을 결합합니다:

  • 실무 마케팅 / 비정기 기고: WordPress 대시보드(cms.mktg.kr)에서 편리하게 작성 및 발행.
  • 심층 기술 문서 / 엔지니어링 릴리즈: 프로젝트 저장소(src/content/blog/)에 마크다운 및 MDX로 직접 커밋하여 코드 리뷰와 자동 빌드 파이프라인 수행.

2. Astro 5 Content Collections 스키마 설계

Astro 5에서는 기존의 로컬 파일 기반 컬렉션을 뛰어넘어 외부 API, 데이터베이스, 로컬 파일을 아우르는 통일된 loader 기반의 Content Layer API가 도입되었습니다.

// src/content.config.ts
import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/blog' }),
  schema: z.object({
    title: z.string(),
    description: z.string().optional(),
    date: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
    author: z.string().default('MKTGLab'),
    category: z.string().default('Modern Web Tech'),
    tags: z.array(z.string()).default([]),
    image: z.string().optional(),
  }),
});

export const collections = { blog };

glob 로더를 사용하면 로컬 디렉토리 내의 대규모 문서들도 빌드 시점에 최적화된 메모리 구조로 색인되며, TypeScript를 통한 엄격한 타입 안정성을 확보할 수 있습니다.

3. 이종(Heterogeneous) 데이터 스트림의 정규화 (Normalization)

로컬 마크다운 파일과 워드프레스 REST/GraphQL 응답은 필드명과 구조가 서로 다릅니다. 이를 프론트엔드 컴포넌트에서 매번 분기 처리하면 템플릿 코드가 복잡해집니다.

따라서 데이터 수집 단계에서 공통 인터페이스(UnifiedPost)로 변환하는 정규화 레이어를 구축하는 것이 필수적입니다.

export interface UnifiedPost {
  id: string;
  slug: string;
  title: string;
  date: string;
  modified?: string;
  excerpt: string;
  content?: string;
  author: {
    name: string;
    description?: string;
    url?: string;
  };
  category: {
    name: string;
    slug: string;
  };
  tags: string[];
  image?: string;
  source: 'local' | 'wordpress';
  localEntry?: any;
}

정규화 계층에서는:

  • 발행일 기준 통합 정렬: 로컬 글과 워드프레스 글을 new Date(b.date).getTime() - new Date(a.date).getTime()으로 일괄 정렬하여 타임라인 순서를 일관되게 유지합니다.
  • 슬러그 충돌 방지: 만약 로컬 파일명과 워드프레스 포스트 슬러그가 동일할 경우, 우선순위 정책(예: 로컬 Git 우선 또는 WP 덮어쓰기 방지)을 수립합니다.
  • 카테고리 매핑: 로컬 글의 카테고리 텍스트를 공식 슬러그(예: Modern Web Tech → modern-web)와 매핑하여 사이드바 및 카테고리 아카이브와 유기적으로 연결합니다.

4. 렌더링 전략: Markdown Component vs HTML Injection

상세 페이지(src/pages/blog/[slug].astro)에서는 글의 출처(source)에 따라 렌더링 방식을 우아하게 분기합니다:

  • 로컬 마크다운 (source: 'local'): Astro 5의 render(post.localEntry) 헬퍼를 통해 Astro 컴포넌트 <Content />를 렌더링합니다. Astro 빌드 엔진이 구문 강조(Shiki), 테이블, 코드 블록을 완벽하게 컴파일합니다.
  • 워드프레스 포스트 (source: 'wordpress'): WP Gutenberg가 생성한 정제된 HTML을 <section class="prose" set:html={post.content} />를 통해 주입합니다.

두 방식 모두 모노그래프(Monograph) 테마의 동일한 에디토리얼 타이포그래피, 브레드크럼(홈 > 블로그 > [카테고리] > [제목]), 저자 프로필, 그리고 E-E-A-T 준수 JSON-LD 스키마를 공유합니다.

5. 결론 및 기대 효과

이와 같은 하이브리드 아키텍처를 도입함으로써 얻을 수 있는 이점은 명확합니다:

  1. 개발자 생산성 향상: 테크니컬 문서는 로컬 IDE에서 마크다운으로 빠르게 작성하고 Git으로 버전 관리할 수 있습니다.
  2. 비개발팀 협업 유지: 마케팅 팀은 별도의 코드 지식 없이도 워드프레스 관리자 화면을 통해 콘텐츠를 자유롭게 발행할 수 있습니다.
  3. 완벽한 Core Web Vitals: 브라우저는 오직 순수 HTML/CSS와 최소한의 아일랜드 자바스크립트만을 다운로드하므로 LCP, CLS, INP 전 영역에서 녹색(Good) 점수를 유지할 수 있습니다.

KEEP READING