📝 블로그 포스팅 거버넌스

이 문서는 GitHub Pages + Jekyll 기반 블로그에서 읽기 쉽고 전파력 있는 글을 쓰기 위한 가이드입니다. 개발 중 알게 된 것을 블로그 방문자에게 쉽게 전달하는 것이 목표입니다.

1. 글쓰기 철학 3원칙

2. 포스트 구조 템플릿

모든 포스트는 아래 6단 구조를 따릅니다.

┌─────────────────────────────────────┐
│  🎯 Hook (1~2문장)                  │  ← 왜 이 글을 쓰는가? 무엇을 얻나?
├─────────────────────────────────────┤
│  📋 TL;DR (3~5개 불릿)              │  ← 바쁜 사람을 위한 핵심 요약
├─────────────────────────────────────┤
│  🔍 배경 / 문제 상황                 │  ← 무엇을 하려 했고, 무엇이 막혔나?
├─────────────────────────────────────┤
│  💡 해결 과정 (메인 본문)            │  ← 단계별 설명 + 그림/코드/표
├─────────────────────────────────────┤
│  ✅ 결과 / Before & After            │  ← 해결 결과를 시각적으로
├─────────────────────────────────────┤
│  📌 Takeaway (핵심 교훈 3가지)       │  ← 한 줄씩 기억할 것
└─────────────────────────────────────┘

각 섹션 작성 가이드

🎯 Hook — 첫 문장이 모든 것을 결정한다

❌ "이 글에서는 Cloudflare Workers에 대해 알아보겠습니다."
✅ "무료로 하루 10만 요청을 처리하는 API를 만들 수 있습니다 — Cloudflare Workers로요."

• 독자의 pain point나 호기심을 자극하는 한 문장으로 시작
• “X를 해결했다”, “Y를 무료로 만들었다”, “Z 때문에 3일을 날렸다” 패턴 활용

📋 TL;DR — 바쁜 사람을 배려하라

## TL;DR

- Cloudflare Pages + Workers + D1 조합으로 **월 $0** 웹서비스 구축 가능
- 핵심은 `@opennextjs/cloudflare` 어댑터로 Next.js를 Pages에 올리는 것
- D1(SQLite)은 5GB까지 무료, R2는 egress 요금 없음

• 3~5개 불릿, 각 핵심에 굵은 글씨로 키워드 강조
• 이것만 읽어도 글의 목적을 아는 수준으로

🔍 배경 — “왜 이걸 하게 되었나”를 먼저 말하라

• 독자가 공감할 수 있는 상황을 먼저 설명
• 인프라/환경 설명은 간단한 아키텍처 다이어그램 하나로
• “A를 하려 했는데 B가 안 되었다” → 독자도 같은 문제를 겪고 있을 가능성

💡 해결 과정 — Step by Step

• 큰 단락은 번호가 있는 단계로 나누기 (Step 1, Step 2, …)
• 2개 이상의 선택지가 있다면 비교표 사용
• 코드는 핵심만 — 전체 코드는 GitHub 링크나 접을 수 있는 블록(<details>)으로

✅ 결과 — 시각적으로 보여라

• Before & After 이미지 or 표
• 숫자가 있다면 개선 수치 표시 (예: “응답 시간 2.3s → 0.4s”)
• 스크린샷, 다이어그램, 아키텍처 그림 최소 1개 이상

📌 Takeaway — 기억할 것 3가지

## Takeaway

1. **302 + Set-Cookie는 Cloudflare Pages에서 불안정하다** — 200 HTML + JS 리다이렉트로 대체
2. **다중 쿠키는 `Headers.append()`로** — 생성자는 쉼표로 병합함
3. **프론트엔드와 API는 같은 도메인에** — Pages Functions가 CORS 없이 깔끔

3. 시각 자료 가이드 — “글만 있는 글은 문서다”

3.1 언제 어떤 시각 자료를 쓸까

3.2 다이어그램 작성

Jekyll에서 Mermaid를 지원하지 않는 경우, 텍스트 다이어그램을 사용:

┌──────────┐    OAuth     ┌──────────┐   SQL    ┌─────┐
│  SPA     │ ──────────→  │  Worker  │ ──────→  │ D1  │
│ (Pages)  │ ←──────────  │ (/api/*) │ ←──────  │     │
└──────────┘   JWT/JSON   └──────────┘   rows   └─────┘

또는 코드 블록 안에 ASCII 아트로 간단한 흐름도를 그린다.

3.3 이미지 사용 규칙

• 이미지 위치: /assets/images/posts/{포스트슬러그}/ 아래에 저장
• 파일명: 01-problem-overview.png, 02-architecture.png (숫자 접두사로 순서 표시)
• 크기: 가로 800px 이하 (모바일 가독성)
• 대체 텍스트: 모든 이미지에 ![설명](경로) 형식으로 설명 필수

<!-- ✅ 좋은 예 -->
![OAuth 로그인 흐름: SPA → Pages Functions → Google → 콜백](/assets/images/posts/oauth-toubleshooting/01-oauth-flow.png)

<!-- ❌ 나쁜 예 -->
![이미지](image.png)

4. 코드 작성 규칙

4.1 코드는 최소화하라

<!-- ❌ 나쁜 예: 100줄 전체 코드를 그대로 붙여넣음 -->

<!-- ✅ 좋은 예: 핵심만 보여주고, 전체는 링크로 -->

핵심 로직만 10~20줄 이내로 보여준다. 전체 코드가 필요한 경우:

<details>
<summary>📖 전체 코드 보기</summary>

```typescript
// 전체 코드를 여기에

</details>

### 4.2 코드에는 반드시 설명을

```typescript
// ✅ 좋은 예: 각 단계에 주석
const token = await generateJWT(user.id);     // 1. JWT 생성
res.cookies.set('token', token, {             // 2. HttpOnly 쿠키로 설정
  httpOnly: true,
  secure: true,
  sameSite: 'lax'
});

4.3 에러 코드는 원인과 함께

### ❌ 에러

429 Too Many Requests — {“error”:{“code”:”1113”,”message”:”余额不足”}}

**원인**: `/api/paas/v4/` 경로는 일반 리소스 풀을 사용하여 쉽게 고갈됨
**해결**: `/api/coding/paas/v4/` 경로 사용 (별도 리소스 풀)

5. 글쓰기 스타일 규칙

5.1 문장 규칙

5.2 톤 & 매너

• 격식 있되 딱딱하지 않게: “~합니다” 체 (존댓말)
• 독자에게 직접 말하듯: “설정하세요”, “확인해보세요”
• 솔직하게: “여기서 3일을 날렸다”, “공식 문서에 안 적혀 있었다”
• 과장 금지: “완벽한”, “최고의” → 구체적인 수치나 사실로 대체

5.3 글 길이 가이드

글이 길어지면 여러 포스트로 나눈다. 하나의 포스트 = 하나의 핵심 메시지.

6. Jekyll 프론트매터 규격

---
layout: post
title: 제목은 검색에 잘 걸리게 (한글 가능)
categories: [카테고리1, 카테고리2]      # 2~3개, 대분류 → 소분류
description: 검색결과에 표시될 한 줄 요약  # 80자 이내
keywords: [키워드1, 키워드2, 키워드3]    # 3~7개
toc: true
toc_sticky: true
---

제목 작성 규칙

❌ "Cloudflare에 대해 알아보자"              → 너무 모호
❌ "Cloudflare Pages + Workers + D1 + R2 완벽 가이드" → 과장
✅ "Cloudflare 스택으로 월 $0 웹서비스 만들기"         → 구체적, 효용 명확
✅ "GLM-5 API 429 에러 — 3일간의 삽질과 해결"          → 경험 기반, 호기심 유발

7. 출간 전 체크리스트

내용 체크

• Hook: 첫 문장이 호기심을 자극하는가?
• TL;DR: 바쁜 독자도 요약만 읽고 갈 수 있는가?
• 시각 자료: 다이어그램, 표, 스크린샷 중 최소 1개 있는가?
• Before & After: 결과를 시각적으로 보여주는가?
• Takeaway: 기억할 핵심 3가지가 명확한가?
• 개인정보: 프로젝트명, 이메일, API 키, 도메인이 제거되었는가?

가독성 체크

• 단락 나눔: 3문장 이상 연속 붙어있는 단락이 없는가?
• 굵은 글씨: 각 섹션에 키워드가 강조되어 있는가?
• 표 활용: 나열형 정보가 표로 정리되어 있는가?
• 코드 최소화: 20줄 이상의 코드는 접기 블록으로 감추었는가?
• 헤딩 구조: H2(##)는 5~8개, H3(###)는 그 아래 2~4개인가?

기술 체크

• 프론트매터: layout, title, categories, description, keywords가 있는가?
• 이미지 경로: /assets/images/posts/{슬러그}/ 아래에 있는가?
• 링크: 외부 링크가 정상 작동하는가?
• 로컬 빌드: bundle exec jekyll serve로 렌더링이 정상인가?

8. 포스트 유형별 템플릿

Type A: How-To 가이드

---
layout: post
title: "___하는 방법 — ___부터 ___까지"
categories: [대분류, 소분류]
description: "___"
keywords: [...]
toc: true
toc_sticky: true
---

{Hook: 왜 이걸 해야 하나? 한 문장}

## TL;DR
- 핵심 요약 3~5개

## 사전 준비
- 필요 조건 불릿

## Step 1: ___
설명 + 코드/이미지

## Step 2: ___
설명 + 코드/이미지

## 결과
Before & After 이미지 or 표

## Takeaway
1. **핵심 1**
2. **핵심 2**
3. **핵심 3**

Type B: 트러블슈팅

---
layout: post
title: "___ 에러 해결 — ___했더니 고쳐짐"
---

{Hook: 어떤 상황에서 어떤 에러가 났다}

## TL;DR
- 에러 원인 한 줄
- 해결 방법 한 줄

## 에러 내용

에러 로그

## 원인 분석
다이어그램 or 설명

## 해결 과정
### 시도 1: ___ → ❌ 실패 (이유)
### 시도 2: ___ → ❌ 실패 (이유)
### 시도 3: ___ → ✅ 성공

## Takeaway
1. **핵심 교훈**

Type C: 비교 / 리뷰

---
layout: post
title: "___ vs ___ — ___기준으로 비교해봤다"
---

{Hook: 왜 이 비교가 필요한가}

## 비교 표
| 항목 | A | B |
|------|---|---|
| ... | ... | ... |

## A의 장단점
## B의 장단점
## 결론
## Takeaway

Type D: 개념 설명

---
layout: post
title: "___란? — ___관점에서 이해하기"
---

{Hook: 이 개념을 왜 알아야 하나}

## 한 줄 정의
___란 ___이다.

## 왜 필요한가
실제 사례

## 핵심 원리
다이어그램 + 설명

## 실전 예시
코드

## Takeaway

9. 멀티소스 통합 포스트 작성법

여러 개발 노트를 하나의 포스트로 합칠 때:

1. 소스별 핵심 메시지를 한 줄로 추출
2. 공통 주제로 그룹핑
3. 서사 흐름 구성: 문제 → 원인 → 해결 → 교훈
4. 각 소스의 중복 내용 제거
5. 통합 후 글 길이가 8,000자 초과 → 포스트 분리

이 거버넌스는 지속적으로 개선됩니다. 포스트를 작성하며 발견한 개선점은 이 문서에 반영합니다.