mdx-render

name

mdx-render

description

Use when converting a finalized 3-Zone chapter YAML (plus optional dashboard.yml) into Docusaurus MDX files — generating frontmatter with authors/ai_assisted/source metadata, importing custom components, placing components in the editor-specified render_order, writing the /appendix dashboard page, and preserving backups of previously written MDX. Also use when deciding which part-XX/ folder a chapter belongs to.

mdx-render

Overview

파이프라인 최종 단계. 편집·보강 완료된 YAML을 독자가 볼 Docusaurus MDX 파일로 출력한다. Human-only 필드는 커스텀 컴포넌트 props로만 전달해 "사람 영역"임이 시각적으로도 드러나게 한다.

어투와 섹션 이모지: 렌더링 시 추가하는 H2/H3 헤딩(예: "👃 코드 냄새 맡아보기", "✏️ 개선해보기")과 산문 브릿지는 writing-voice-ff 스킬의 역할형 이모지 표와 해요체 원칙을 따른다. 커스텀 컴포넌트 내부 텍스트는 YAML literal 그대로 (어투 가이드 적용 안 함).

When to Use

• chapter-editor + fe-content-enhancer 산출물이 준비되고 최종 MDX 생성이 필요할 때
• aggregator 대시보드 YAML로 /appendix 페이지를 만들 때
• 기존 MDX를 덮어쓸 때 (백업 포함)

출력 파일 위치

대상	경로	매핑 규칙
챕터 MDX	docs/part-{NN}/ch{XX}.mdx	장수 → Part 매핑 표 참조
부록 대시보드	docs/appendix/dashboard.mdx	고정 경로
백업	_workspace/_prev/{timestamp}/{원경로}	타임스탬프 폴더

장수 → Part 매핑

장수	Part
1~4	part-01
5~9	part-02
10~13	part-03
14~19	part-04
20~24	part-05
25~31	part-06
32~35	part-07

Frontmatter 필수 필드

---
sidebar_position: 5                       # 장수 그대로
title: "Chapter 5. 고급 변수 종류"         # meta.title 그대로
description: "..."                        # summary.lead 1문장
authors:                                  # opinions 작성 멤버 + devils_advocate 작성자 (중복 제거)
  - Alice
  - diego
ai_assisted:                              # AI가 손댄 섹션만 나열
  - summary
  - code_examples
  - checklist
  - verdict.rationale                     # AI가 초안 제공한 경우만
source: notion-pull
source_page_id: xxx
extracted_at: 2026-04-18T22:30:00+09:00
edited_at: 2026-04-18T22:45:00+09:00
---

컴포넌트 import (모든 챕터 공통)

import Verdict from '@site/src/components/Verdict';
import MemberOpinion from '@site/src/components/MemberOpinion';
import VotingBar from '@site/src/components/VotingBar';
import DevilsAdvocate from '@site/src/components/DevilsAdvocate';
import BestPickCallout from '@site/src/components/BestPickCallout';

부록 전용:

import VerdictDistribution from '@site/src/components/VerdictDistribution';
import BestDiscussions from '@site/src/components/BestDiscussions';

챕터 MDX 템플릿 (render_order 준수)

YAML render_order가 지정한 순서대로 섹션 출력. 기본값 예시:

---
<frontmatter>
---

<imports>

<Verdict rating="🟢 생존" rationale="..." />

## 📝 핵심 요약

{lead}

- {bullets[0]}
- {bullets[1]}
- {bullets[2]}

{bridges.after_summary ?? ''}

<VotingBar average={4.2} votes={{ Alice: 4, Amber: 5, Crong: 3, diego: 4, Jay: 5, Leo: 4, zinii: 3 }} />

## 💻 React/TS 코드 예제

### {code_examples[0].title}

**Before ❌**

```typescript
{code_examples[0].before}

After ✅

{code_examples[0].after}

🔥 토론 포인트 & 생각해볼 질문

1. {discussion_questions[0]}
2. {discussion_questions[1]}
3. {discussion_questions[2]}

{bridges.before_opinions ?? ''}

💬 멤버 의견

✅ FE 실전 체크리스트

• {checklist[0].text} — 관련 ESLint: {rule}
• {checklist[1].text}

```

부록 MDX 템플릿

---
sidebar_position: 99
title: "📊 스터디 대시보드"
description: "Code Complete 스터디 전체 집계 — 판정 분포, 투표 평균, 베스트 토론"
---

import VerdictDistribution from '@site/src/components/VerdictDistribution';
import BestDiscussions from '@site/src/components/BestDiscussions';

## 스터디 진행 현황

- 진행된 챕터: {chapters_included}
- 참여 멤버: {members_count}명

## ⚖️ 판정 분포

<VerdictDistribution alive={5} evolved={2} dead={1} />

## 📊 투표 요약

- 전체 평균: **{overall_average}** / 5

### 챕터별 평균

| 챕터 | 평균 | 판정 |
|---|---|---|
| ch01 | 4.2 | 🟢 생존 |
| ch02 | 3.5 | 🟡 변형 |

### 최고 평가 TOP 3

1. Chapter 5 — 고급 변수 종류 (4.7)

### 최저 평가 TOP 3

1. Chapter 6 — ... (2.1)

## 💎 베스트 토론

<BestDiscussions items={[...]} />

## 😈 Devil's Advocate 모음

> **ch05 (diego):** ...

## 멤버 활동

| 멤버 | 의견 작성 | 반박 담당 | 투표 제출 |
|---|---|---|---|
| Alice 🦊 | 8 | 1 | 8 |

렌더 규칙

1. 빈 필드 처리:
   • member_opinions에서 opinion 없는 멤버 → 해당 <MemberOpinion> 태그 자체를 생략 (빈 말풍선 금지)
   • devils_advocate null → <DevilsAdvocate> 섹션 전체 생략
   • best_pick.content null → <BestPickCallout> 생략
   • code_examples 0개 → "💻 React/TS 코드 예제" H2도 생략
2. MDX 특수문자 이스케이프: {, } → {, } (코드 블록 외)
3. 사이드바 순서: sidebar_position은 장수 그대로. 테마 재배치 시 별도 sidebars.ts 수정 (이 스킬 범위 밖)
4. 검증: 출력 직후 npm run docusaurus build --dry-run이 가능한 상태여야 함 (실제 실행은 호출자 책임)

백업 규칙

기존 docs/part-NN/chXX.mdx 존재 시:

1. _workspace/_prev/{YYYYMMDD-HHMMSS}/docs/part-NN/chXX.mdx로 복사
2. 원본 위치 덮어쓰기
3. git 저장소면 diff로도 추적 가능하지만 안전장치 유지

Common Mistakes

실수	결과	수정
opinion props 텍스트에 줄바꿈	JSX 렌더 깨짐	\n을 {"\n"} 또는 <br />로
authors에 zinii 누락 (opinion 없음)	기여 없는 사람이 author로 기록	opinions/advocate 작성자만 authors
frontmatter에 ai_assisted 빈 배열	false 인상 (AI 무개입처럼 보임)	최소 [] 명시, null/생략 금지
sidebar_position을 render_order로 혼동	사이드바 순서 뒤죽박죽	sidebar_position은 항상 장수