본 문서는 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대 카테고리 중 하나를 지정합니다:
Modern Web Tech: Astro, Headless CMS, 엣지 배포, 웹 성능 최적화Technical SEO: 엔티티 온톨로지, Schema.org 구조화 데이터, 크롤링 최적화Data & Growth: 데이터 파이프라인, 마케팅 엔지니어링, 트래킹, 퍼널 분석AI & Search: GEO(생성형 엔진 최적화), AI 크롤러 제어, LLM 지식 인덱싱
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 번들 로딩)", "취약 (사전 렌더링 부재)", "복잡한 웹 애플리케이션"]
]}
/>
실제 렌더링 결과:
| 렌더링 모델 | 초기 로딩 속도 | 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
Web Framework
콘텐츠 중심 웹사이트를 위한 초고속 웹 프레임워크이자 제로 JS 아키텍처 지원 도구
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) 없이 작동하며, 접혀 있는 상태에서도 크롤러 색인과 브라우저 텍스트 검색 시 자동 펼침을 완벽히 지원합니다."
}
]}
/>
실제 렌더링 결과:
Astro 시맨틱 컴포넌트 및 스키마 마크업 관련 핵심 Q&A
Q1.시맨틱 컴포넌트를 사용하면 검색엔진(SEO)과 AI 검색(GEO)에 어떤 이점이 있나요?
Q2.아코디언으로 접혀 있는 답변 텍스트도 브라우저 페이지 내 검색(Ctrl+F)과 크롤링이 되나요?
요소를 사용하여 클라이언트 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% 보존합니다.
<!-- 캡션이 있는 이미지:  -->

<!-- 캡션이 없는 일반 이미지:  -->

- 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 본문에서 자동으로 호버 툴팁이 활성화되도록 하는 표준 절차입니다:
- 마스터 파일 편집 (
src/data/glossary.csv):src/data/glossary.csv파일의 마지막 행에 새 용어를 추가합니다.- 필수 9개 컬럼:
No,카테고리,표준 용어명,영문/원어 표기,핵심 정의 및 원리,실무 적용 및 비즈니스 영향,구현 가이드 및 주의사항,code_example(선택),심화 설명.
- 동기화 스크립트 실행:
- 터미널에서 다음 명령어를 실행하여 JSON 컴파일 및 슬러그 검증을 완료합니다:
npm run update:glossary - 스크립트가 영문 원어를 기반으로 클린 URL 슬러그를 자동 발급하고, 중복 여부를 검증한 후
src/data/glossary.json에 안전하게 반영합니다.
- 터미널에서 다음 명령어를 실행하여 JSON 컴파일 및 슬러그 검증을 완료합니다:
- 특수 약어 및 띄어쓰기 별칭 등록 (선택 사항):
- 만약 본문에서 자주 쓰이는 영문 약어(예:
RSC,CWV)나 특정 띄어쓰기 형태를 자동 매칭하고 싶다면,src/lib/autoLinker.ts의TECHNICAL_ALIASES객체에 해당 슬러그와 키워드를 추가합니다.
- 만약 본문에서 자주 쓰이는 영문 약어(예:
- 결과 확인:
- 로컬 개발 서버(
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 규격
| 속성명 (Prop) | 타입 / 허용 값 | 기본값 | 설명 |
|---|---|---|---|
| type | 'bar' | 'horizontalBar' | 'line' | 'area' | 'bubble' | 'scatter' | 'doughnut' | 'pie' | 'radar' | 'polarArea' | 'funnel' | 'sankey' | 'treemap' | 'bar' | 생성할 차트의 종류 지정 |
| title | string | '' | 차트 카드 상단 헤더 라벨 (모노스페이스 대문자 스타일) |
| subtitle | string | '' | 차트 타이틀 아래 보조 설명 텍스트 |
| caption | string | '' | 차트 하단 시맨틱 <figcaption> 설명 또는 데이터 출처 |
| data | { labels?: string[], datasets: any[] } | 필수 | 차트에 렌더링할 라벨 및 데이터셋 배열 |
| valueFormat | 'number' | 'percent' | 'currency' | 'kb' | 'ms' | 'number' | 축 눈금 및 호버 툴팁 수치 자동 포맷팅 ('percent'는 0.67 → 67% 또는 67 → 67% 자동 변환) |
| yMax | number | 자동 | Y축(수평 막대는 X축) 최대값 고정 (예: 비율 비교 시 1 또는 100) |
| legend | boolean | 'top' | 'bottom' | 'left' | 'right' | 자동 | 범례 표시 여부 및 위치 지정 |
| stacked | boolean | false | 누적 막대/누적 꺾은선 차트 활성화 여부 |
| height | number | string | 340 | 차트 캔버스 영역 높이 (예: 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]
}
]
}}
/>
HTTP Archive 및 CrUX 실사용자 데이터 기준 프레임워크별 CWV 통과율
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] }
]
}}
/>
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 }] }
]
}}
/>
X축: 페이지당 평균 JS 전송량(KB) / Y축: 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]
}
]
}}
/>
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]
}
]
}}
/>
오가닉 검색 노출부터 리드 전환까지의 4단계 마케팅 퍼널
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 }
]
}
]
}}
/>
유입 검색엔진 → 첫 랜딩 콘텐츠 → 전환 액션까지의 트래픽 흐름도
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"
}
]
}}
/>
핵심 토픽 클러스터별 월간 오가닉 검색 볼륨 비중
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를 실행하는 구조이므로, 일반 마크다운보다 엄격한 구문 규칙이 적용됩니다:
- 컴포넌트 자동 주입 활용 (
import선언 불필요):SemanticTable,SoftwareCard,PersonBadge,Chart는 동적 라우트([slug].astro) 템플릿의componentsprop으로 자동 주입됩니다.- 따라서 MDX 문서 상단에 별도의
import구문을 작성하지 않고 바로 태그를 호출해야 합니다. - 주의: MDX 상단에
@/components/...와 같이 별칭(@/)으로 직접 import를 선언하면 Vite 개발 서버(RunnableDevEnvironment) 모듈 러너에서Cannot find module '@/components/...'오류가 발생합니다.
- 신규 커스텀 컴포넌트 추가 시:
- 템플릿에 전역 등록되지 않은 새로운 컴포넌트를 import해야 할 때는
@/별칭 대신 상대 경로(예:import MyComponent from '../../components/MyComponent.astro')를 사용하거나,[slug].astro의mdxComponents에 등록하여 전역 컴포넌트로 주입하는 방식을 권장합니다.
- 템플릿에 전역 등록되지 않은 새로운 컴포넌트를 import해야 할 때는
- 부등호, 중괄호 이스케이프 및 볼드(
**) 닫힘 띄어쓰기 규칙:- 본문에서
< 0.5s,{value},<Component>처럼 태그나 자바스크립트 객체로 오인될 수 있는 기호는 반드시 백틱(`)으로 감싸 인라인 코드로 작성하세요. - 괄호/인라인 코드 뒤
**닫힘 주의 (CommonMark Delimiter Rule):**정적 이미지(PNG)**를또는**Hugo(휴고)**나처럼 닫는**바로 앞 글자가 닫는 괄호()), 백틱(`), 따옴표(',") 등 문장부호일 때 뒤에 한글 조사(를,이,은,나등)가 띄어쓰기 없이 바로 붙으면 마크다운 파서가 볼드 종료를 인식하지 못하고**기호가 화면에 그대로 노출됩니다. 반드시**정적 이미지(PNG)** 를처럼 닫는**뒤에 한 칸을 띄워 쓰거나, 조사까지 포함해 문장을 다듬어야 합니다.
- 본문에서
7. 생성형 AI 리서치 활용 및 프롬프트 고지 원칙 (AI Attribution & Privacy)
mktg.kr의 심층 리서치 아티클 작성 시 Google Gemini Research, ChatGPT, Claude 등의 대규모 언어 모델을 보조 도구로 활용할 수 있습니다. 이때 다음 원칙을 엄격히 준수해야 합니다:
- 원시 프롬프트 채팅방/공유 링크 비공개 원칙 (Strict No-Link Policy):
- 글 작성 요청 시 제공된 Gemini Research 세션 링크, ChatGPT 공유 URL 등 작성자가 실행한 원시 프롬프트와 세부 대화 로그가 담긴 링크는 외부에 절대 노출하지 않습니다.
- 작성자의 고유한 프롬프트 엔지니어링 지적 자산(IP) 보호, 내부 질문 맥락 유출 방지 및 세션 만료에 따른 404 깨진 링크(Dead Link) 리스크를 원천 차단하기 위함입니다.
- 도구 활용 명시 및 휴먼 에디터 검증 고지:
- 아티클 말미의
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. 결론 및 향후 계획
문서의 결론과 실무 권장 사항을 정리하며 마무리합니다.