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

v2.1 Playbook·Modern Web Tech

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

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

작성자: ·분류: Modern Web Tech··구글 검색 선호 출처 등록
📖 목차 (TABLE OF CONTENTS)펼치기 / 접기

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

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


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

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

  • 블로그 (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: "MKTG Edge"                      # 기본값: MKTG Edge (필요시 필자명)
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: "정상원 (MKTG Edge)"             # 기본값: 정상원 (MKTG Edge)
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대 카테고리 중 하나를 지정합니다:


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

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

💡 컴포넌트 자동 주입 안내
<SemanticTable />, <SemanticFAQ /> (또는 <FAQ />), <SoftwareCard />, <PersonBadge />, <YouTubeEmbed /> (또는 <YouTube />), <LinkCard /> (또는 <BookmarkCard />), <Chart />는 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="MKTG Edge"
  avatar="/images/authors/sangwon.jpeg"
  url="https://mktg.kr/about"
  sameAs={["https://www.linkedin.com/in/jeongsangwon/"]}
/>

실제 렌더링 결과:

3.4 시맨틱 FAQ 아코디언 (<SemanticFAQ /> / <FAQ />)

구글 리치 결과(Rich Results), PAA(People Also Ask), 그리고 생성형 AI 검색(GEO) 인용 최적화를 위해 FAQPage Schema.org JSON-LD를 자동 생성하는 네이티브 HTML5 <details> / <summary> 기반 Zero-JS 아코디언 컴포넌트입니다. <SemanticFAQ /> 또는 축약형 별칭인 <FAQ />로 호출할 수 있습니다.

<SemanticFAQ
  title="자주 묻는 질문 (FAQ)"
  subtitle="Astro 시맨틱 컴포넌트 및 스키마 마크업 관련 핵심 Q&A"
  exclusive={true}
  items={[
    {
      question: "시맨틱 컴포넌트를 사용하면 검색엔진(SEO)과 AI 검색(GEO)에 어떤 이점이 있나요?",
      answer: "본문의 시각적 UI와 100% 일치하는 Schema.org JSON-LD(FAQPage, SoftwareApplication, Person 등)가 빌드 시점에 자동 주입되어 리치 결과 노출 및 LLM 지식 그래프 인용 확률을 높여줍니다."
    },
    {
      question: "아코디언으로 접혀 있는 답변 텍스트도 브라우저 페이지 내 검색(Ctrl+F)과 크롤링이 되나요?",
      answer: "네, 표준 HTML5 <details>와 <summary> 요소를 사용하여 클라이언트 JS(0KB) 없이 작동하며, 접혀 있는 상태에서도 크롤러 색인과 브라우저 텍스트 검색 시 자동 펼침을 완벽히 지원합니다."
    }
  ]}
/>

실제 렌더링 결과:

자주 묻는 질문 (FAQ)

Astro 시맨틱 컴포넌트 및 스키마 마크업 관련 핵심 Q&A

Q1.시맨틱 컴포넌트를 사용하면 검색엔진(SEO)과 AI 검색(GEO)에 어떤 이점이 있나요?
본문의 시각적 UI와 100% 일치하는 Schema.org JSON-LD(FAQPage, SoftwareApplication, Person 등)가 빌드 시점에 자동 주입되어 리치 결과 노출 및 LLM 지식 그래프 인용 확률을 높여줍니다.
Q2.아코디언으로 접혀 있는 답변 텍스트도 브라우저 페이지 내 검색(Ctrl+F)과 크롤링이 되나요?
네, 표준 HTML5
와 요소를 사용하여 클라이언트 JS(0KB) 없이 작동하며, 접혀 있는 상태에서도 크롤러 색인과 브라우저 텍스트 검색 시 자동 펼침을 완벽히 지원합니다.

3.5 YouTube 비디오 임베드 (<YouTubeEmbed /> / <YouTube />)

YouTube 영상 URL만 입력하면 16:9 Lite Facade 플레이어를 렌더링하고, YouTube oEmbed 메타데이터 조회 및 VideoObject Schema.org JSON-LD를 자동으로 주입합니다.

{/* URL만 입력해도 제목/채널명/썸네일/VideoObject 스키마 자동 생성 */}
<YouTube url="https://www.youtube.com/watch?v=dsTXcSeAZq8" />

{/* 상세 스키마 메타데이터 직접 지정 */}
<YouTubeEmbed
  url="https://www.youtube.com/watch?v=dsTXcSeAZq8"
  title="Astro in 100 Seconds — 초고속 웹 프레임워크 개요"
  description="Astro 웹 프레임워크 및 아일랜드 아키텍처 핵심 개념 요약 영상"
  uploadDate="2022-08-09"
  duration="PT2M32S"
  caption="영상 1: Astro의 아일랜드 아키텍처와 Zero-JS 작동 원리"
/>

3.6 외부 URL 프리뷰 북마크 카드 (<LinkCard /> / <BookmarkCard />)

외부 또는 내부 URL을 입력하면 대상 페이지의 Open Graph(og:image, og:title, og:description)와 파비콘을 자동으로 추출해 썸네일 북마크 박스로 렌더링합니다.

{/* URL만 입력하여 Open Graph 메타데이터 자동 추출 */}
<LinkCard url="https://docs.astro.build/en/concepts/islands/" />

{/* 타이틀·설명·썸네일을 명시적으로 지정하는 방식 */}
<LinkCard
  url="https://docs.astro.build/en/concepts/islands/"
  title="Astro Islands Architecture — 공식 아키텍처 문서"
  description="정적 HTML 페이지 안에서 인터랙티브한 UI 컴포넌트만 독립된 섬(Island)처럼 병렬 하이드레이션하는 Astro의 핵심 설계 철학을 설명합니다."
  siteName="Astro Docs"
  image="https://astro.build/_astro/social.FlPxeRsG.jpg"
/>

3.7 본문 시맨틱 이미지와 캡션 (<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.8 순수 마크다운(.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.9 본문 내 용어사전 호버 툴팁 (Glossary Tooltip & Auto-Linker)

블로그와 Docs 본문 내에 MKTG Edge 용어사전에 등록된 235종의 마케팅 테크/SEO 전문 용어가 등장하면, 마우스 오버(Hover) 또는 모바일 탭(Tap) 시 핵심 정의와 작동 원리가 팝업 툴팁으로 표시됩니다.

1) 자동 치환 방식 (권장)

일반 마크다운 문장 작성 시 용어 키워드를 그대로 작성하면 렌더링 파이프라인에서 자동으로 감지하여 툴팁 트리거로 래핑합니다:

  • 자동 변환 형태: <a href="/glossary/[slug]" class="glossary-term" data-glossary-...>[용어]</a>
  • 중복 방지: 동일 문단/문서 내 최초 1회만 치환되어 시각적 피로도를 방지합니다.
  • 예외 제외 태그: <a>, <h1>~<h6>, <code>, <pre>, <button> 등 내부 텍스트는 치환에서 엄격히 제외됩니다.

2) MDX 컴포넌트 방식 (<Term />, <GlossaryTooltip />)

특정 위치에서 명시적으로 용어사전 툴팁을 적용하고자 할 때 전역 주입된 <Term /> 컴포넌트를 직접 호출할 수 있습니다:

<!-- 용어명 자동 바인딩 -->
최신 웹 아키텍처에서는 <Term name="SSG" /> 방식을 적용합니다.

<!-- 사용자 지정 텍스트 래핑 -->
정적 렌더링의 대표적인 예로 <Term name="SSG">정적 사이트 생성 기법</Term>이 있습니다.

<!-- 슬러그 기반 지정 -->
헤드리스 아키텍처의 핵심인 <Term slug="headless-content-management-system">헤드리스 CMS</Term> 연동 가이드입니다.
  • 주요 특징:
    • 모노그래프 미니멀 테마(다크 모드 완벽 호환, 은은한 점선 언더라인)
    • 뷰포트 좌우 가장자리 충돌 방지 클램핑 및 상/하 반전(Flip) 자동 계산
    • 터치 디바이스(모바일) 탭 대응 및 키보드 접근성(Tab/Escape) 완비

3) 신규 기술 용어 추가 및 동기화 가이드

새로운 기술 용어를 사전에 등록하여 블로그 및 Docs 본문에서 자동으로 호버 툴팁이 활성화되도록 하는 표준 절차입니다:

  1. 마스터 파일 편집 (src/data/glossary.csv):
    • src/data/glossary.csv 파일의 마지막 행에 새 용어를 추가합니다.
    • 필수 9개 컬럼: No, 카테고리, 표준 용어명, 영문/원어 표기, 핵심 정의 및 원리, 실무 적용 및 비즈니스 영향, 구현 가이드 및 주의사항, code_example(선택), 심화 설명.
  2. 동기화 스크립트 실행:
    • 터미널에서 다음 명령어를 실행하여 JSON 컴파일 및 슬러그 검증을 완료합니다:
      npm run update:glossary
    • 스크립트가 영문 원어를 기반으로 클린 URL 슬러그를 자동 발급하고, 중복 여부를 검증한 후 src/data/glossary.json에 안전하게 반영합니다.
  3. 특수 약어 및 띄어쓰기 별칭 등록 (선택 사항):
    • 만약 본문에서 자주 쓰이는 영문 약어(예: RSC, CWV)나 특정 띄어쓰기 형태를 자동 매칭하고 싶다면, src/lib/autoLinker.ts의 TECHNICAL_ALIASES 객체에 해당 슬러그와 키워드를 추가합니다.
  4. 결과 확인:
    • 로컬 개발 서버(npm run dev)를 실행 중이라면 새로고침만으로 즉시 새 용어에 대한 툴팁과 전용 상세 페이지(/glossary/[slug])가 생성됩니다.

4. 데이터 시각화 차트 (<Chart />) 생성 가이드

Astro 공식 벤치마크 리포트와 동일한 Chart.js v4 엔진 및 마케팅 특화 확장 플러그인(Funnel, Sankey, Treemap)이 통합된 범용 시맨틱 차트 컴포넌트입니다.

  • 전역 주입 완료: 별도의 import 없이 MDX 본문 어디서나 <Chart ... />로 즉시 호출합니다.
  • 다크/라이트 모드 실시간 동기화: 사이트 테마 전환 시 그리드, 라벨, 툴팁 색상이 즉시 자동 전환됩니다.
  • 크롤러/접근성 폴백(Fallback) 내장: <canvas> 내부에 검색엔진 봇(Googlebot, Yeti, AI 봇)과 스크린 리더가 읽을 수 있는 정적 데이터 <table>이 자동으로 생성됩니다.

4.1 <Chart /> 공통 Props 규격

표 2: <Chart /> 컴포넌트 속성(Props) 명세
표 2: <Chart /> 컴포넌트 속성(Props) 명세
속성명 (Prop)타입 / 허용 값기본값설명
type'bar' | 'horizontalBar' | 'line' | 'area' | 'bubble' | 'scatter' | 'doughnut' | 'pie' | 'radar' | 'polarArea' | 'funnel' | 'sankey' | 'treemap''bar'생성할 차트의 종류 지정
titlestring''차트 카드 상단 헤더 라벨 (모노스페이스 대문자 스타일)
subtitlestring''차트 타이틀 아래 보조 설명 텍스트
captionstring''차트 하단 시맨틱 <figcaption> 설명 또는 데이터 출처
data{ labels?: string[], datasets: any[] }필수차트에 렌더링할 라벨 및 데이터셋 배열
valueFormat'number' | 'percent' | 'currency' | 'kb' | 'ms''number'축 눈금 및 호버 툴팁 수치 자동 포맷팅 ('percent'는 0.67 → 67% 또는 67 → 67% 자동 변환)
yMaxnumber자동Y축(수평 막대는 X축) 최대값 고정 (예: 비율 비교 시 1 또는 100)
legendboolean | 'top' | 'bottom' | 'left' | 'right'자동범례 표시 여부 및 위치 지정
stackedbooleanfalse누적 막대/누적 꺾은선 차트 활성화 여부
heightnumber | string340차트 캔버스 영역 높이 (예: 320, '400px')

4.2 기본 차트 입력 및 생성 예시

1) 막대 차트 (bar / horizontalBar) — Astro CWV 리포트 스타일

단일 지표 비교나 프레임워크/채널별 성과 비교에 사용합니다. valueFormat="percent"와 yMax={1}을 지정하면 0~1 사이의 소수 데이터를 깔끔한 백분율(0% ~ 100%)로 표시합니다.

<Chart
  type="bar"
  title="% Sites Passing Core Web Vitals"
  subtitle="HTTP Archive 및 CrUX 실사용자 데이터 기준 프레임워크별 CWV 통과율"
  caption="그림 1: 웹 프레임워크별 Core Web Vitals 통과 비율 (출처: CrUX & HTTP Archive)"
  valueFormat="percent"
  yMax={1}
  data={{
    labels: ["Astro", "SvelteKit", "Gatsby", "Remix", "WordPress", "Next.js", "Nuxt"],
    datasets: [
      {
        label: "CWV 통과율",
        data: [0.67, 0.45, 0.394, 0.358, 0.304, 0.275, 0.202]
      }
    ]
  }}
/>
% Sites Passing Core Web Vitals

HTTP Archive 및 CrUX 실사용자 데이터 기준 프레임워크별 CWV 통과율

% Sites Passing Core Web Vitals
항목CWV 통과율
Astro0.67
SvelteKit0.45
Gatsby0.394
Remix0.358
WordPress0.304
Next.js0.275
Nuxt0.202
그림 1: 웹 프레임워크별 Core Web Vitals 통과 비율 (출처: CrUX & HTTP Archive)

2) 다중 그룹 / 분위수 비교 막대 차트 (Grouped Bar)

datasets 배열에 여러 객체를 넣으면 자동으로 색상 팔레트와 우측 상단 범례(Legend)가 생성되며, 범례를 클릭해 특정 지표만 켜고 끌 수 있습니다.

<Chart
  type="bar"
  title="Lighthouse Performance Score, Breakdown"
  caption="그림 2: 프레임워크별 Lighthouse 성능 점수 분위수(p25 ~ p95) 분포"
  valueFormat="percent"
  yMax={1}
  data={{
    labels: ["Astro", "SvelteKit", "Remix", "Gatsby", "Next.js", "Nuxt"],
    datasets: [
      { label: "p25", data: [0.44, 0.33, 0.29, 0.18, 0.19, 0.16] },
      { label: "p50 (Median)", data: [0.65, 0.52, 0.46, 0.32, 0.30, 0.25] },
      { label: "p75", data: [0.87, 0.73, 0.59, 0.55, 0.47, 0.37] },
      { label: "p90", data: [0.98, 0.89, 0.80, 0.68, 0.63, 0.54] }
    ]
  }}
/>
Lighthouse Performance Score, Breakdown
Lighthouse Performance Score, Breakdown
항목p25p50 (Median)p75p90
Astro0.440.650.870.98
SvelteKit0.330.520.730.89
Remix0.290.460.590.8
Gatsby0.180.320.550.68
Next.js0.190.30.470.63
Nuxt0.160.250.370.54
그림 2: 프레임워크별 Lighthouse 성능 점수 분위수(p25 ~ p95) 분포

3) 버블 차트 (bubble) — 3차원 상관관계 분석

$X$축 수치(x), $Y$축 수치(y), 그리고 원의 반지름 크기(r)를 입력하여 두 지표 간의 상관관계와 볼륨을 동시에 표현합니다.

<Chart
  type="bubble"
  title="Median KB of JavaScript vs. % Sites Passing CWV"
  subtitle="X축: 페이지당 평균 JS 전송량(KB) / Y축: CWV 통과율(%)"
  caption="그림 3: 자바스크립트 번들 용량이 증가할수록 CWV 통과율이 급격히 하락하는 음의 상관관계"
  valueFormat="percent"
  legend="left"
  data={{
    datasets: [
      { label: "Astro", data: [{ x: 277, y: 0.67, r: 11 }] },
      { label: "SvelteKit", data: [{ x: 324, y: 0.45, r: 10 }] },
      { label: "Remix", data: [{ x: 569, y: 0.36, r: 10 }] },
      { label: "Gatsby", data: [{ x: 846, y: 0.39, r: 10 }] },
      { label: "Next.js", data: [{ x: 885, y: 0.27, r: 11 }] },
      { label: "Nuxt", data: [{ x: 928, y: 0.20, r: 10 }] }
    ]
  }}
/>
Median KB of JavaScript vs. % Sites Passing CWV

X축: 페이지당 평균 JS 전송량(KB) / Y축: CWV 통과율(%)

그림 3: 자바스크립트 번들 용량이 증가할수록 CWV 통과율이 급격히 하락하는 음의 상관관계

4) 시계열 추이 / 영역 차트 (line / area)

시간 흐름에 따른 오가닉 트래픽 변화, 색인 수 추이, 응답 속도 변화를 시각화할 때 사용합니다. type="area"를 쓰면 선 아래 영역에 반투명 그라데이션이 채워집니다.

<Chart
  type="area"
  title="IndexNow 도입 전후 일별 크롤링 및 색인 반영 추이"
  caption="그림 4: IndexNow 즉시 푸시 적용 이후 신규 문서 색인 도달률 변화"
  valueFormat="percent"
  yMax={100}
  data={{
    labels: ["D+1", "D+2", "D+3", "D+5", "D+7", "D+14"],
    datasets: [
      {
        label: "IndexNow 즉시 제출 (%)",
        data: [78, 91, 95, 98, 99, 99.5]
      },
      {
        label: "기존 사이트맵 자연 수집 (%)",
        data: [12, 24, 38, 55, 68, 84]
      }
    ]
  }}
/>
IndexNow 도입 전후 일별 크롤링 및 색인 반영 추이
IndexNow 도입 전후 일별 크롤링 및 색인 반영 추이
항목IndexNow 즉시 제출 (%)기존 사이트맵 자연 수집 (%)
D+17812
D+29124
D+39538
D+59855
D+79968
D+1499.584
그림 4: IndexNow 즉시 푸시 적용 이후 신규 문서 색인 도달률 변화

4.3 마케팅 & 그로스 특화 확장 차트 생성 가이드 (Funnel, Sankey, Treemap)

1) 마케팅 퍼널 차트 (type="funnel")

노출 → 클릭 → 상세 조회 → 전환으로 이어지는 단계별 볼륨 감소를 위에서 아래로 좁아지는 사다리꼴 퍼널 형태로 시각화합니다.

  • 입력 방법: labels에 퍼널 단계명을 순서대로 배열하고, datasets[0].data에 각 단계의 수치를 입력합니다.
<Chart
  type="funnel"
  title="Organic Search to Lead Conversion Funnel"
  subtitle="오가닉 검색 노출부터 리드 전환까지의 4단계 마케팅 퍼널"
  caption="그림 5: 테크니컬 아티클 오가닉 유입 후 뉴스레터/문의 전환 퍼널"
  height={300}
  data={{
    labels: [
      "1단계: SERP 노출 (Impressions)",
      "2단계: 오가닉 클릭 유입 (Clicks)",
      "3단계: 아티클 75% 완독 (Engaged)",
      "4단계: 뉴스레터/리드 전환 (Converted)"
    ],
    datasets: [
      {
        label: "사용자 수",
        data: [10000, 3200, 1450, 420]
      }
    ]
  }}
/>
Organic Search to Lead Conversion Funnel

오가닉 검색 노출부터 리드 전환까지의 4단계 마케팅 퍼널

Organic Search to Lead Conversion Funnel
항목사용자 수
1단계: SERP 노출 (Impressions)10000
2단계: 오가닉 클릭 유입 (Clicks)3200
3단계: 아티클 75% 완독 (Engaged)1450
4단계: 뉴스레터/리드 전환 (Converted)420
그림 5: 테크니컬 아티클 오가닉 유입 후 뉴스레터/문의 전환 퍼널

2) 고객 여정 흐름도 / 생키 다이어그램 (type="sankey")

유입 채널(Source)에서 랜딩 페이지(Landing), 그리고 최종 전환 행동(Action)으로 이어지는 다대다(Many-to-Many) 트래픽 흐름을 시각화합니다.

  • 입력 방법: datasets[0].data 배열 안에 { from: '출발 노드', to: '도착 노드', flow: 가중치수치 } 형태의 객체를 나열합니다.
<Chart
  type="sankey"
  title="Multi-Channel User Journey Flow (Sankey)"
  subtitle="유입 검색엔진 → 첫 랜딩 콘텐츠 → 전환 액션까지의 트래픽 흐름도"
  caption="그림 6: 검색 및 AI 엔진 유입 사용자의 콘텐츠 소비 및 전환 여정"
  height={340}
  data={{
    datasets: [
      {
        label: "트래픽 흐름",
        data: [
          { from: "Google 검색", to: "기술 블로그", flow: 55 },
          { from: "Google 검색", to: "용어사전 (Glossary)", flow: 30 },
          { from: "AI 검색 (Perplexity/ChatGPT)", to: "Docs 플레이북", flow: 25 },
          { from: "NAVER 검색", to: "기술 블로그", flow: 20 },
          { from: "기술 블로그", to: "Docs 플레이북", flow: 35 },
          { from: "기술 블로그", to: "리드 전환", flow: 40 },
          { from: "용어사전 (Glossary)", to: "기술 블로그", flow: 20 },
          { from: "Docs 플레이북", to: "리드 전환", flow: 45 }
        ]
      }
    ]
  }}
/>
Multi-Channel User Journey Flow (Sankey)

유입 검색엔진 → 첫 랜딩 콘텐츠 → 전환 액션까지의 트래픽 흐름도

그림 6: 검색 및 AI 엔진 유입 사용자의 콘텐츠 소비 및 전환 여정

3) 키워드 볼륨 트리맵 (type="treemap")

토픽 클러스터나 키워드 그룹별 검색량(또는 트래픽 비중)을 사각형 면적으로 비례하여 한눈에 비교합니다.

  • 입력 방법: datasets[0] 안에 tree 배열(각 항목에 { label: '이름', value: 수치 })과 key: 'value'를 지정합니다.
<Chart
  type="treemap"
  title="Topic Cluster Monthly Search Volume Treemap"
  subtitle="핵심 토픽 클러스터별 월간 오가닉 검색 볼륨 비중"
  caption="그림 7: MKTG Edge 주요 기술 토픽 클러스터별 검색 수요 비중"
  height={320}
  data={{
    datasets: [
      {
        label: "월간 검색 볼륨",
        tree: [
          { label: "Technical SEO & Schema", value: 4200 },
          { label: "Astro & Edge SSR", value: 3100 },
          { label: "GEO / AI Search Optimization", value: 2800 },
          { label: "Core Web Vitals (INP/LCP)", value: 2100 },
          { label: "Headless CMS Architecture", value: 1650 },
          { label: "GA4 & Server-side GTM", value: 1400 }
        ],
        key: "value"
      }
    ]
  }}
/>
Topic Cluster Monthly Search Volume Treemap

핵심 토픽 클러스터별 월간 오가닉 검색 볼륨 비중

그림 7: MKTG Edge 주요 기술 토픽 클러스터별 검색 수요 비중

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

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

5.1 헤딩(Heading) 위계 규칙

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

5.2 인용구(Blockquote) 및 강조

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

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

5.3 코드 블록 및 언어 명시

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

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

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

  1. 컴포넌트 자동 주입 활용 (import 선언 불필요):
    • SemanticTable, SoftwareCard, PersonBadge, Chart는 동적 라우트([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>처럼 태그나 자바스크립트 객체로 오인될 수 있는 기호는 반드시 백틱(`)으로 감싸 인라인 코드로 작성하세요.
    • 괄호/인라인 코드 뒤 ** 닫힘 주의 (CommonMark Delimiter Rule): **정적 이미지(PNG)**를 또는 **Hugo(휴고)**나처럼 닫는 ** 바로 앞 글자가 닫는 괄호()), 백틱(`), 따옴표(', ") 등 문장부호일 때 뒤에 한글 조사(를, 이, 은, 나 등)가 띄어쓰기 없이 바로 붙으면 마크다운 파서가 볼드 종료를 인식하지 못하고 ** 기호가 화면에 그대로 노출됩니다. 반드시 **정적 이미지(PNG)** 를처럼 닫는 ** 뒤에 한 칸을 띄워 쓰거나, 조사까지 포함해 문장을 다듬어야 합니다.

7. 생성형 AI 리서치 활용 및 프롬프트 고지 원칙 (AI Attribution & Privacy)

mktg.kr의 심층 리서치 아티클 작성 시 Google Gemini Research, ChatGPT, Claude 등의 대규모 언어 모델을 보조 도구로 활용할 수 있습니다. 이때 다음 원칙을 엄격히 준수해야 합니다:

  1. 원시 프롬프트 채팅방/공유 링크 비공개 원칙 (Strict No-Link Policy):
    • 글 작성 요청 시 제공된 Gemini Research 세션 링크, ChatGPT 공유 URL 등 작성자가 실행한 원시 프롬프트와 세부 대화 로그가 담긴 링크는 외부에 절대 노출하지 않습니다.
    • 작성자의 고유한 프롬프트 엔지니어링 지적 자산(IP) 보호, 내부 질문 맥락 유출 방지 및 세션 만료에 따른 404 깨진 링크(Dead Link) 리스크를 원천 차단하기 위함입니다.
  2. 도구 활용 명시 및 휴먼 에디터 검증 고지:
    • 아티클 말미의 RESEARCH METHODOLOGY & EDITORIAL DISCLOSURE 박스에는 활용한 도구의 명칭만 볼드(strong)로 표기합니다.
    • 인간 에디터가 사실관계와 엔지니어링 맥락을 재검수한 ‘Human-in-the-Loop’ 원칙을 명시하고, 사이트의 공식 Editorial & AI Policy 링크로 연결합니다.

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

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

---
title: "여기에 문서 제목을 입력하세요"
description: "문서의 핵심 내용을 간결하게 설명하는 1~2문장의 디스크립션입니다."
author: "MKTG Edge"
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. 결론 및 향후 계획

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