MKTGLab

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

v2.0 Playbook·Modern Web Tech

MKTGLab 콘텐츠 엔지니어링 및 MDX 작성 가이드

mktg.kr의 블로그 아티클과 Docs 엔지니어링 플레이북 작성을 위한 표준 규격, Frontmatter 스키마, 시맨틱 컴포넌트(<SemanticTable />, <SoftwareCard />) 활용법 및 작성 수칙.

작성자: MKTGLab·분류: Modern Web Tech··
📖 목차 (TABLE OF CONTENTS)펼치기 / 접기

본 문서는 mktg.kr에 기고되는 블로그 아티클(Blog) 과 엔지니어링 플레이북(Docs) 을 일관되고 완성도 높게 작성하기 위한 실무 표준 가이드입니다.

Astro 5의 Content Layer와 MDX 통합 환경을 기반으로, 모노그래프(Monograph) 특유의 정갈한 미니멀리즘과 검색엔진/AI 검색(GEO)을 위한 시맨틱 마크업 구조를 준수하는 방법을 안내합니다.

1. 콘텐츠 아키텍처 개요 및 파일 배치 규칙

MKTGLab의 콘텐츠는 목적에 따라 두 가지 컬렉션으로 분리 운용됩니다:

  • 블로그 (src/content/blog/): 트렌드 분석, 기술 케이스 스터디, 심층 칼럼 등 에디토리얼 성격의 아티클.
    • 경로: src/content/blog/[slug].mdx (또는 .md)
    • URL: https://mktg.kr/blog/[slug]
  • Docs 플레이북 (src/content/docs/): 개발 가이드, 아키텍처 다이어그램, 규격서, 실무 체크리스트 등 레퍼런스 문서.
    • 경로: src/content/docs/[slug].mdx (또는 .md)
    • URL: https://mktg.kr/docs/[slug]

2. 컬렉션별 Frontmatter 스키마 규격

모든 문서는 상단에 YAML 형식의 Frontmatter(--- 블록)를 포함해야 합니다.

2.1 블로그 아티클 규격 (src/content/blog/*.mdx)

---
title: "아티클 제목 (간결하고 직관적인 문장형)"
description: "검색엔진 스니펫 및 소셜 공유 메타태그에 노출되는 1~2문장의 핵심 요약문."
author: "MKTGLab"                      # 기본값: MKTGLab (필요시 필자명)
category: "Modern Web Tech"            # 카테고리 (하단 참조)
date: "2026-09-24"                     # YYYY-MM-DD
updatedDate: "2026-09-24"             # 최종 수정일 (선택)
tags:
  - "Astro 5"
  - "Headless WordPress"
  - "Core Web Vitals"
image: "/images/blog/sample-hero.png"  # 대표 히어로 이미지 경로 (선택)
imageAlt: "이미지에 대한 접근성 설명 텍스트" # 이미지 alt 속성 (선택)
imageCaption: "이미지 하단에 표시될 시맨틱 figcaption 설명 텍스트 (선택)"
---

2.2 Docs 플레이북 규격 (src/content/docs/*.mdx)

---
title: "문서 제목 (플레이북/가이드 명칭)"
description: "이 문서가 다루는 기술 영역과 달성 목표에 대한 개요."
author: "정상원 (MKTGLab)"             # 기본값: 정상원 (MKTGLab)
category: "Modern Web Tech"            # 카테고리
date: "2026-09-24"
updatedDate: "2026-09-30"              # 최종 수정일 (문서 개정 시 필수 추가, sitemap lastmod 및 메타데이터 자동 반영)
version: "v2.0 Playbook"               # 문서 버전 배지 (기본값: v2.0 Playbook)
readingTime: "8"                       # 예상 읽는 시간 (분)
sections:                              # Docs 인덱스 카드에 노출되는 주요 목차 아웃라인
  - "Section 1. 개요 및 인프라 설계"
  - "Section 2. 시맨틱 컴포넌트 규격"
  - "Section 3. 실무 체크리스트"
tags:
  - "Astro"
  - "시맨틱 마크업"
  - "가이드"
---

2.3 지원 카테고리 목록

사이트 내 일관된 분류 체계를 위해 다음 4대 카테고리 중 하나를 지정합니다:

  • Modern Web Tech: Astro, Headless CMS, 엣지 배포, 웹 성능 최적화
  • Technical SEO: 엔티티 온톨로지, Schema.org 구조화 데이터, 크롤링 최적화
  • Data & Growth: 데이터 파이프라인, 마케팅 엔지니어링, 트래킹, 퍼널 분석
  • AI & Search: GEO(생성형 엔진 최적화), AI 크롤러 제어, LLM 지식 인덱싱

3. 시맨틱 MDX 컴포넌트 활용 가이드

MDX 문서에서는 표준 마크다운 문법 외에 MKTGLab 전용 시맨틱 컴포넌트를 자유롭게 삽입할 수 있습니다.

💡 컴포넌트 자동 주입 안내
<SemanticTable />, <SoftwareCard />, <PersonBadge />는 Astro 레이아웃 템플릿에 전역 컴포넌트로 사전 주입(Global Injection)되어 있습니다. 따라서 MDX 상단에 별도의 import 문을 작성할 필요 없이 본문에서 태그만 바로 호출하면 됩니다.

3.1 시맨틱 테이블 (<SemanticTable />)

카드형 외곽 박스를 배제하고 미니멀한 단일 상단선과 행 구분선으로 모던한 디자인을 구현한 반응형 테이블입니다. 표 상단에 독립적인 메타 라벨을 렌더링하며, 스크린 리더와 검색엔진을 위한 숨김 <caption>을 자동 지원합니다.

<SemanticTable 
  caption="표 1: 주요 웹 렌더링 모델별 성능 비교표"
  headers={["렌더링 모델", "초기 로딩 속도", "SEO 친화도", "주요 용도"]}
  rows={[
    ["정적 사이트 생성 (SSG)", "가장 빠름 (TTFB < 50ms)", "최상 (완전한 정적 HTML)", "블로그, 문서, 랜딩페이지"],
    ["서버 사이드 렌더링 (SSR)", "보통 (서버 연산 필요)", "우수 (크롤러 친화적)", "개인화 대시보드, 커머스"],
    ["클라이언트 렌더링 (CSR)", "느림 (JS 번들 로딩)", "취약 (사전 렌더링 부재)", "복잡한 웹 애플리케이션"]
  ]}
/>

실제 렌더링 결과:

표 1: 주요 웹 렌더링 모델별 성능 비교표
표 1: 주요 웹 렌더링 모델별 성능 비교표
렌더링 모델초기 로딩 속도SEO 친화도주요 용도
정적 사이트 생성 (SSG)가장 빠름 (TTFB < 50ms)최상 (완전한 정적 HTML)블로그, 문서, 랜딩페이지
서버 사이드 렌더링 (SSR)보통 (서버 연산 필요)우수 (크롤러 친화적)개인화 대시보드, 커머스
클라이언트 렌더링 (CSR)느림 (JS 번들 로딩)취약 (사전 렌더링 부재)복잡한 웹 애플리케이션

3.2 소프트웨어 카드 (<SoftwareCard />)

도구나 소프트웨어를 소개할 때 사용하는 구조화 컴포넌트입니다. 배포 시 SoftwareApplication Schema.org JSON-LD를 자동 주입하여 검색엔진과 AI가 제품 스펙을 즉시 식별할 수 있도록 합니다.

<SoftwareCard 
  name="Astro"
  applicationCategory="Web Framework"
  operatingSystem="Cross-platform"
  price="Free (MIT)"
  rating="4.9"
  logo="/images/logos/astro-icon.svg"
  description="콘텐츠 중심 웹사이트를 위한 초고속 웹 프레임워크이자 제로 JS 아키텍처 지원 도구"
  url="https://astro.build"
/>

실제 렌더링 결과:

Astro

Astro

Web Framework

★ 4.9 / 5.0

콘텐츠 중심 웹사이트를 위한 초고속 웹 프레임워크이자 제로 JS 아키텍처 지원 도구

OS 환경Cross-platform
가격 정책Free (MIT)
공식 사이트

3.3 저자/전문가 배지 (<PersonBadge />)

아티클 내에서 특정 인용구나 기여자를 명시할 때 사용하는 시맨틱 컴포넌트입니다. 배포 시 Person Schema.org JSON-LD를 자동 주입하여 저자 정보를 구조화합니다.

<PersonBadge 
  name="정상원"
  jobTitle="Head of Marketing Engineering"
  affiliation="MKTGLab"
  avatar="/images/authors/sangwon.jpeg"
  url="https://mktg.kr/about"
  sameAs={["https://www.linkedin.com/in/jeongsangwon/"]}
/>

실제 렌더링 결과:

3.4 본문 시맨틱 이미지와 캡션 (<figure>, <figcaption>)

.md 및 .mdx 모두에서 이미지 하단에 설명 문구를 넣을 때 HTML5 <figure>와 <figcaption> 구조로 자동 변환됩니다. 본문 너비와 무관하게 수평 정중앙 정렬되며, 잘림(크롭) 없이 원본 종횡비(Aspect Ratio)를 100% 보존합니다.

<!-- 캡션이 있는 이미지: ![대체텍스트](이미지URL "캡션 텍스트") -->
![Astro 아키텍처 다이어그램](/images/blog/sample-diagram.png "그림 1: Astro와 Headless CMS 연동 파이프라인")

<!-- 캡션이 없는 일반 이미지: ![대체텍스트](이미지URL) -->
![웹 성능 벤치마크 결과](/images/blog/benchmark-chart.png)
  • HTML 변환 결과: 
    <figure class="article-image">
  <img src="/images/blog/sample-diagram.png" alt="Astro 아키텍처 다이어그램" loading="lazy" decoding="async" />
  <figcaption>그림 1: Astro와 Headless CMS 연동 파이프라인</figcaption>
</figure>

3.5 순수 마크다운(.md)을 위한 표준 시맨틱 HTML5 테이블

.md 파일(또는 Notion, WordPress)에서는 MDX 컴포넌트(<SemanticTable />)를 직접 쓸 수 없으므로, 표준 HTML5 <table> 마크업을 사용합니다. 사이트의 모노그래프 디자인 시스템과 반응형 가로 스크롤이 자동으로 적용됩니다:

<table>
  <caption>표 1: 주요 웹 퍼블리싱 프레임워크 기술 스택 비교</caption>
  <thead>
    <tr>
      <th scope="col">프레임워크</th>
      <th scope="col">기반 언어</th>
      <th scope="col">렌더링 모델</th>
      <th scope="col">권장 CMS</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row">Astro</th>
      <td>JavaScript / TypeScript</td>
      <td>Islands Architecture (SSG/SSR)</td>
      <td>Notion, WordPress, Markdown</td>
    </tr>
    <tr>
      <th scope="row">Next.js</th>
      <td>React (TypeScript)</td>
      <td>App Router (RSC, SSR)</td>
      <td>Headless CMS, REST API</td>
    </tr>
  </tbody>
  <tfoot>
    <tr>
      <th scope="row">권장</th>
      <td colspan="3">콘텐츠 중심 미디어/블로그는 Zero-JS 기반 Astro 권장</td>
    </tr>
  </tfoot>
</table>

3.6 용어사전(Glossary) 235종 자동 인터널 링킹 (Auto-Linker)

블로그와 Docs 본문 내에 MKTGLab 용어사전에 등록된 235종의 마케팅 테크/SEO 전문 용어가 등장하면, 문서당 최초 1회에 한해 자동으로 용어사전 링크와 툴팁이 삽입됩니다:

  • 자동 변환 형태: <a href="/glossary/[slug]" class="glossary-link" title="[용어 간략 설명]">[용어]</a>
  • 치환 안전 예외: <a>, <h1>~<h6>, <code>, <pre>, <img alt="..." 내부 텍스트는 치환 대상에서 자동으로 제외되므로, 링크 중첩이나 태그 깨짐이 발생하지 않습니다.

4. 타이포그래피 계층 및 마크다운 작성 수칙

사이트의 시각적 일관성과 가독성을 위해 아래 규칙을 엄수합니다:

4.1 헤딩(Heading) 위계 규칙

  • H1 (#) 사용 금지: 페이지 제목(H1)은 레이아웃 템플릿이 Frontmatter의 title을 이용해 자동 생성합니다. 본문에서는 절대로 #를 사용하지 마세요.
  • 주요 단락은 H2 (##): 본문의 주요 장(Chapter)은 ## 1. 섹션명 형태로 작성합니다. (font-weight: 700, font-size: 1.5rem 고정)
  • 세부 소제목은 H3 (###): 세부 항목은 ### 1.1 항목명으로 작성합니다.
  • H3 하위 설명은 불릿 리스트 (-) 권장: H3 아래 긴 문장을 뭉쳐 쓰기보다, - **핵심 키워드**: 상세 설명 구조로 요약하면 가독성이 대폭 향상됩니다.

4.2 인용구(Blockquote) 및 강조

  • 문장의 도입부 핵심 리드문이나 중요한 인용문은 > 블록을 사용합니다.
  • 예시:

    “프론트엔드는 제로 JS로 빠르게, 백엔드는 검증된 CMS로 안전하게.”

4.3 코드 블록 및 언어 명시

  • 코드 블록은 반드시 세 개의 백틱(```)과 함께 정확한 언어 식별자(typescript, bash, html, yaml, mermaid 등)를 지정합니다.

5. MDX 작성 시 주의사항 및 체크리스트

MDX는 마크다운 안에서 JSX를 실행하는 구조이므로, 일반 마크다운보다 엄격한 구문 규칙이 적용됩니다:

  1. 컴포넌트 자동 주입 활용 (import 선언 불필요):
    • SemanticTable, SoftwareCard, PersonBadge는 동적 라우트([slug].astro) 템플릿의 components prop으로 자동 주입됩니다.
    • 따라서 MDX 문서 상단에 별도의 import 구문을 작성하지 않고 바로 태그를 호출해야 합니다.
    • 주의: MDX 상단에 @/components/...와 같이 별칭(@/)으로 직접 import를 선언하면 Vite 개발 서버(RunnableDevEnvironment) 모듈 러너에서 Cannot find module '@/components/...' 오류가 발생합니다.
  2. 신규 커스텀 컴포넌트 추가 시:
    • 템플릿에 전역 등록되지 않은 새로운 컴포넌트를 import해야 할 때는 @/ 별칭 대신 상대 경로(예: import MyComponent from '../../components/MyComponent.astro')를 사용하거나, [slug].astro의 mdxComponents에 등록하여 전역 컴포넌트로 주입하는 방식을 권장합니다.
  3. 부등호 및 중괄호 이스케이프:
    • 본문에서 < 0.5s, {value}, <Component>처럼 태그나 자바스크립트 객체로 오인될 수 있는 기호는 반드시 백틱(`)으로 감싸 인라인 코드로 작성하세요.

6. 바로 복사해서 사용하는 기본 MDX 템플릿

새로운 문서를 작성할 때 아래 템플릿을 복사하여 시작할 수 있습니다:

---
title: "여기에 문서 제목을 입력하세요"
description: "문서의 핵심 내용을 간결하게 설명하는 1~2문장의 디스크립션입니다."
author: "MKTGLab"
category: "Modern Web Tech"
date: "2026-09-24"
readingTime: "6"
version: "v2.0 Playbook"
sections:
  - "Section 1. 도입 배경 및 목표"
  - "Section 2. 핵심 아키텍처 설계"
  - "Section 3. 실측 성능 지표 및 비교"
tags:
  - "Astro 5"
  - "MDX"
---

> **"여기에 아티클의 핵심 슬로건이나 요약 인용구를 작성합니다."**

본격적인 도입 배경과 서론을 작성합니다.

---

## 1. 도입 배경 및 목표

기존 환경의 문제점과 이를 해결하기 위한 엔지니어링 목표를 서술합니다.

### 1.1 해결해야 할 과제
- **성능 저하**: 클라이언트 자바스크립트 비대화로 인한 TBT 악화.
- **유지보수 비용**: 분산된 스키마로 인한 데이터 정합성 결여.

---

## 2. 핵심 아키텍처 설계

구현한 시스템의 구조를 설명하고 시맨틱 컴포넌트를 활용합니다.

<SemanticTable 
  caption="표 1: 실무 아키텍처 벤치마크"
  headers={["구분", "기존 방식", "신규 아키텍처"]}
  rows={[
    ["TTFB", "800ms", "< 50ms"],
    ["TBT", "350ms", "0ms"],
    ["CLS", "0.15", "0"]
  ]}
/>

---

## 3. 결론 및 향후 계획

문서의 결론과 실무 권장 사항을 정리하며 마무리합니다.