📋 템플릿 — 복사해서 시작
한 줄 답: 새 문서·챕터·다이어그램을 만들 때 이 페이지의 코드 블록을 통째로 복사해서 빈칸을 채우면 7-블록 형식과 Mermaid 색상 규칙이 자동으로 지켜진다.
이 페이지는 CONTRIBUTING.md의 동반자 페이지입니다. 규칙을 읽기 전에, 먼저 복사부터 하세요. 복사 → 빈칸 채우기 → pnpm meta 가 가장 빠른 작성 루프입니다.
1. 본문 문서 템플릿 — 7-블록
새 본문 mdx (예: pages/03-media-video/12-color-space.mdx)를 만들 때 아래 블록 전체를 통째로 복사해서 시작하세요.
---
title: "12 — Color Space"
description: "한 줄 답: 색공간은 RGB·YCbCr·sRGB·Rec.709·BT.2020처럼 *어떤 좌표계로 색을 표현할지의 약속*이고, 카메라·인코더·디스플레이 셋이 같은 약속을 지켜야 색이 맞는다."
---
# 12 — Color Space
> **한 줄 답**: 색공간은 *어떤 좌표계로 색을 표현할지의 약속*이고, 카메라·인코더·디스플레이 셋이 같은 약속을 지켜야 색이 맞는다.
---
## Why — 왜 이 개념이 필요한가
(역사적·문제적 배경. 1-3 단락. "이 개념이 없던 시절에는 어떤 문제가 있었나"를 답한다.)
---
## How — 어떻게 동작하나
### 1) (메커니즘 1)
(코드·수식·표·다이어그램. 본문의 50% 이상을 여기에 쏟는다.)
```c
// 예시 코드
```
### 2) (메커니즘 2)
| 항목 | 값 | 비고 |
|------|---|------|
| ... | ... | ... |
### 3) (메커니즘 3)
```mermaid
flowchart LR
classDef domain fill:#e8f4ff,stroke:#3370b8
A["입력"]:::domain --> B["변환"]:::domain --> C["출력"]:::domain
```
---
## What — 무엇을 알아야 하나
(체크리스트·표·요약. 1-2 단락. 독자가 이 문서에서 가져갈 *재사용 가능한 사실*을 정리한다.)
| 알아야 할 것 | 한 줄 |
|--------------|------|
| ... | ... |
---
## What-if — 이걸 모르면 어떻게 되나
(실패 시나리오·실제 버그·운영 사고. 1-3 단락. "이 개념을 모르고 코드를 짜면 어떤 일이 터지나"를 답한다.)
- 시나리오 A: ...
- 시나리오 B: ...
---
## Insight — 한 단락 이야기
> **"한 줄 인용 또는 일화 제목"**
>
> (역사·일화·관점 1 단락. 독자가 *이 개념을 잊지 않도록* 만드는 한 단락의 이야기.)
---
## 한 단락 요약
> (이 문서의 결론을 한 단락으로. 다음 챕터·문서로 연결되는 화살표 한 줄을 마지막에 둔다.)
> 다음 문서(`13-...`)는 ... 를 다룬다.
```mermaid
flowchart TB
classDef layer fill:#fff8dc,stroke:#aa8800
classDef result fill:#e8ffe8,stroke:#33b833
THIS["12 — Color Space"]:::layer
NEXT["13 — Next Topic"]:::result
THIS --> NEXT
```복사 후 체크: frontmatter
title이 사이드바에 그대로 보입니다.description은 검색 카드에 노출되니 “한 줄 답:“으로 시작하세요.
2. 챕터 개요 템플릿 — index.mdx
새 챕터의 pages/XX-chapter/index.mdx를 만들 때 사용합니다.
---
title: "XX-chapter-slug"
description: "이 챕터가 답하는 질문: ..."
---
# XX-chapter-slug
> **이 챕터가 답하는 질문**: ...
> **한 줄 답**: *"..."*
---
## 한 문장 답 (Pyramid Top)
> (이 챕터 전체의 결론을 한 문장으로. ① ② ③ 같은 번호로 핵심을 분해한다.)
---
## 챕터 지도 (Mermaid)
```mermaid
flowchart TB
classDef layer fill:#fff8dc,stroke:#aa8800
classDef domain fill:#e8f4ff,stroke:#3370b8
classDef danger fill:#ffe8e8,stroke:#b83333
classDef result fill:#e8ffe8,stroke:#33b833
Q["챕터의 질문"]:::layer
F1["01<br/>제목<br/>한 줄 요약"]:::domain
F2["02<br/>제목<br/>한 줄 요약"]:::domain
F3["03<br/>제목<br/>한 줄 요약"]:::domain
Q --> F1
F1 --> F2
F2 --> F3
F1 -. "왜 이걸 먼저 읽나" .-> F2
F2 -. "왜 이걸 다음에 읽나" .-> F3
NEXT["다음 챕터<br/>YY-next<br/>요약"]:::result
F3 --> NEXT
```
---
## Why — 왜 이 챕터부터 시작하나
(상위 레이어의 어떤 미스터리한 버그가 *여기서* 출발하는지를 구체적 질문으로 나열.)
- "왜 ...?" → `01-...`
- "왜 ...?" → `02-...`
- "왜 ...?" → `03-...`
---
## How — 어떻게 읽나
| # | 파일 | 읽는 데 | 핵심 키워드 |
|---|------|--------|------------|
| 01 | [`01-...`](./01-slug) | 12분 | keyword1, keyword2 |
| 02 | [`02-...`](./02-slug) | 10분 | keyword1, keyword2 |
| 03 | [`03-...`](./03-slug) | 12분 | keyword1, keyword2 |
**의존성**: 02는 01을, 03은 02를 가정한다.
---
## What — 한 페이지 요약 (모든 문서의 핵심 한 줄)
| 문서 | 한 줄 결론 |
|------|-----------|
| 01 | ... |
| 02 | ... |
| 03 | ... |
---
## What-if — 이 챕터를 건너뛰면
- **A를 모르면**: ... 가 터진다.
- **B를 모르면**: ... 가 터진다.
---
## Insight — 한 단락 이야기
> **"이 챕터의 핵심 일화 한 문장"**
>
> (1 단락 이야기. 챕터 전체를 잊지 않게 만드는 비유나 역사적 맥락.)
---
## 한 단락 요약
> (챕터 결론 + 다음 챕터로의 연결.)
> 다음 챕터(`YY-next`)는 ...를 다룬다.메타 자동 생성: 위 파일을 만든 뒤
pnpm meta를 돌리면pages/_meta.ts와pages/XX-chapter/_meta.ts가 자동으로 갱신됩니다. 한글 라벨을 사이드바에 표시하려면scripts/generate-meta.mjs의ROOT_LABELS에 한 줄을 추가하세요.
3. Mermaid 다이어그램 템플릿 4종
3.1 Layered — 계층 분해 (layer + domain)
상위 추상 → 하위 도메인 분해를 보여줄 때.
3.2 Sequence — 시계열·통신 (domain + result)
요청·응답·이벤트 흐름.
sequenceDiagram은 classDef를 직접 받지 않습니다. 대신 노드 라벨로 의미를 표현하세요.
3.3 Decision — 분기/판정 (domain + danger + result)
검증·라우팅·정책 결정 트리.
3.4 Comparison — 대조/비교 (4종 전부)
옳은 길 vs 함정.
4. Frontmatter 템플릿
---
title: "08 — H.264 Codec"
description: "한 줄 답: H.264는 인트라/인터 예측·DCT·CABAC·de-blocking을 GOP 단위로 묶은 블록 단위 비디오 코덱이다."
---| 필드 | 규칙 |
|---|---|
title | 사이드바 라벨 그대로. 영문은 NN — Title (em-dash, 양쪽 공백) |
description | ”한 줄 답:“으로 시작. 검색 카드·SEO에 사용 |
5. 표 템플릿
5.1 비교 표
| 항목 | A | B | 비고 |
|---|---|---|---|
| 속도 | 빠름 | 느림 | 5x 차이 |
| 정확도 | 낮음 | 높음 | 99.9% vs 95% |
| 비용 | 저 | 고 | 0.10 |
5.2 체크리스트 표
| 체크 | 항목 |
|---|---|
| ☐ | frontmatter에 title이 있는가 |
| ☐ | 첫 줄이 한 줄 답인가 |
| ☐ | Mermaid가 최소 1개 있는가 |
6. 한 단락 요약
새 문서를 쓸 때는 §1을 복사하세요. 새 챕터를 만들 때는 §2를 복사하세요. Mermaid 다이어그램이 필요할 때는 §3에서 가장 가까운 형태를 골라 빈칸만 바꾸세요. 모든 템플릿은
CONTRIBUTING.md의 색상 규칙(layer/domain/danger/result)과 7-블록 형식(Why → How → What → What-if → Insight → 요약)을 이미 만족합니다. 빈칸을 채우는 동안 형식을 고민하지 마세요 — 형식은 이미 끝나 있습니다.