📋 템플릿 (공유)📋 템플릿 모음

📋 템플릿 — 복사해서 시작

한 줄 답: 새 문서·챕터·다이어그램을 만들 때 이 페이지의 코드 블록을 통째로 복사해서 빈칸을 채우면 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.tspages/XX-chapter/_meta.ts가 자동으로 갱신됩니다. 한글 라벨을 사이드바에 표시하려면 scripts/generate-meta.mjsROOT_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 비교 표

항목AB비고
속도빠름느림5x 차이
정확도낮음높음99.9% vs 95%
비용0.01vs0.01 vs 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 → 요약)을 이미 만족합니다. 빈칸을 채우는 동안 형식을 고민하지 마세요 — 형식은 이미 끝나 있습니다.