| name | ai-edu-site |
| description | 금융/디스플레이 제조업 직장인 대상 생성형 AI 인터랙티브 교육 사이트. 마크다운 교육자료를 풍부한 학습 경험으로 변환. AI 교육, 교육 웹앱, 다크모드, Mermaid. |
AI Education Site
금융/디스플레이 제조업 직장인을 위한 생성형 AI 인터랙티브 교육 사이트.
6개 마크다운 교육 모듈을 Next.js 기반의 풍부한 학습 경험으로 변환한다.
사이트 구조
/ — 홈: 6개 모듈 카드 그리드
/learn/[moduleId] — 모듈별 인터랙티브 학습 페이지
학습 페이지 (/learn/[moduleId])
- 마크다운 교육자료를 react-markdown으로 풀 렌더링
- 좌측 사이드바 목차 (IntersectionObserver 스크롤 스파이)
- 코드 블록 복사 버튼
- 콜아웃 박스 (💡 팁, 🔑 핵심, ⚠ 주의 — 이모지 자동 감지)
- 구조 다이어그램: Mermaid.js 렌더링
- 반응형 테이블, Before/After 비교 구조
- 다크 모드 지원 (시스템 설정 연동 + 수동 토글)
기술 스택
| 항목 | 기술 |
|---|
| 프레임워크 | Next.js 14+ (App Router, 정적 export) |
| 스타일링 | Tailwind CSS 4 + CSS 커스텀 속성 |
| 폰트 | Pretendard (CDN) |
| 마크다운 | react-markdown + remark-gfm + rehype-highlight |
| 다이어그램 | Mermaid.js |
| 아이콘 | Lucide React |
| 배포 | GitHub Pages (basePath: '/ai-edu') |
프로젝트 구조
site/
├── app/
│ ├── layout.tsx # 루트 레이아웃 (Pretendard, FOUC 방지 스크립트)
│ ├── page.tsx # 홈 (모듈 카드 그리드)
│ ├── globals.css # 라이트/다크 테마 + 프로즈 타이포그래피
│ ├── types.ts # TOCItem 타입
│ ├── lib/
│ │ ├── modules.ts # 모듈 설정 (id, title, description, duration, keywords)
│ │ └── markdown.ts # readModuleMarkdown(), extractTOC(), slugify()
│ ├── components/
│ │ ├── Header.tsx # 사이트 헤더 + ThemeToggle
│ │ ├── ThemeToggle.tsx # 다크모드 토글 (light/dark/system)
│ │ ├── MarkdownRenderer.tsx # react-markdown + 커스텀 컴포넌트
│ │ ├── MermaidDiagram.tsx # Mermaid 다이어그램 렌더러
│ │ ├── TableOfContents.tsx # 사이드바 목차 + 스크롤 스파이
│ │ ├── CopyButton.tsx # 코드 복사 버튼
│ │ └── CalloutBox.tsx # 팁/경고 콜아웃 (MarkdownRenderer 내장)
│ └── learn/
│ └── [moduleId]/page.tsx # 모듈별 학습 페이지
├── content/
│ └── module-1~6.md # 마크다운 교육자료
└── public/ # 정적 파일
핵심 설계 결정
ID 동기화 (TOC ↔ DOM)
slugify() 함수를 lib/markdown.ts에서 공유extractTOC()와 MarkdownRenderer의 h2/h3가 동일한 slugify로 ID 생성- rehype-slug 미사용 — 커스텀 heading 컴포넌트로 직접 ID 부여
다크 모드
- CSS 커스텀 속성 기반 (
--site-bg, --site-text 등)
@media (prefers-color-scheme: dark) 시스템 자동 감지[data-theme="dark"] / [data-theme="light"] 수동 오버라이드- localStorage 저장 + FOUC 방지 인라인 스크립트
- Mermaid 다이어그램도 다크모드 자동 대응
Mermaid 다이어그램
- 교육자료의 구조 설명 ASCII 다이어그램을 Mermaid 코드 블록으로 변환
- 프롬프트 입력 예시 / 실습 복사용 코드는 변환하지 않음
MermaidDiagram.tsx: 클라이언트 렌더링, data-theme 변화 감지
정적 export
output: 'export', basePath: '/ai-edu'- 서버 컴포넌트에서 빌드 타임에 마크다운 파일 읽기
generateStaticParams()로 6개 모듈 경로 사전 생성
디자인 시스템
라이트 테마
--site-bg: #FFFFFF
--site-bg-secondary: #F8FAFC
--site-text: #1A1A2E
--site-text-secondary: #64748B
--site-accent: #2563EB
--site-accent-light: #EFF6FF
--site-border: #E2E8F0
--site-code-bg: #F1F5F9
다크 테마
--site-bg: #0F172A
--site-bg-secondary: #1E293B
--site-text: #E2E8F0
--site-text-secondary: #94A3B8
--site-accent: #60A5FA
--site-accent-light: #1E3A5F
--site-border: #334155
--site-code-bg: #1E293B
타이포그래피
- 폰트: Pretendard (CDN)
- 행간: 1.8 (한글 가독성)
- 코드: Pretendard + ui-monospace 폴백
워크플로우
신규 구축 시
- Next.js 프로젝트 초기화 + 패키지 설치
- 마크다운 교육자료를
content/에 복사
- 구조 다이어그램을 Mermaid 코드 블록으로 변환
- 컴포넌트 개발 (MarkdownRenderer, TOC, CopyButton, MermaidDiagram, ThemeToggle)
- 학습 페이지 라우트 생성
- 다크 모드 CSS 적용
- 빌드 & GitHub Pages 배포
콘텐츠 추가/수정 시
content/module-N.md 수정lib/modules.ts에 모듈 설정 추가/수정npm run build → 배포
에러 핸들링
| 상황 | 전략 |
|---|
| 마크다운 파싱 실패 | 해당 모듈 notFound() 반환 |
| Mermaid 렌더링 실패 | 원본 코드 텍스트 폴백 표시 |
| TOC ID 불일치 | slugify() 공유 함수로 방지 |
| 다크모드 FOUC | 인라인 스크립트로 paint 전 테마 적용 |
| 빌드 에러 | TypeScript 에러 우선 해결 |
