Jinhyeon Kwon

Academic portfolio

영문 중심의 대학원생 포트폴리오. 한글과 영문을 지원하는 Pretendard를 사용합니다. 모든 내용(소개 + 전체 CV)을 한 페이지(/)에 보여주며, 라이트/다크 모드를 지원합니다(기본값은 OS 설정, 우측 상단 버튼으로 전환). 예전 /cv/ 주소는 /로 리다이렉트됩니다.

1. 내 콘텐츠로 교체

content/portfolio.json을 편집합니다. 처음 제공되는 인물·소속·논문·수상 이력은 모두 예시입니다. SNS도 실제 개인 계정이 아닌 서비스 시작 페이지를 가리킵니다. 실제 정보로 교체한 후 sample을 false로 바꾸면 예시 안내가 사라집니다.

• design: 사이트 디자인. 모두 라이트/다크 모드를 지원합니다.
  • "modern"(기본): 산세리프, 상단 섹션 메뉴, 좌측 섹션 제목
  • "editorial": 세리프, 좌측 고정 프로필 사이드바, 논문 목록 스타일
  • "terminal": 모노스페이스 포인트(JetBrains Mono), ## 섹션 제목, 좌측 날짜 열, [paper] 형태 링크
  • "card": 연회색 배경 위 흰 카드, 이니셜 아바타, 논문별 카드, 짧은 목록은 2단 배치
  • "mono-accent": 스위스 스타일 큰 이름, 12단 그리드, 흑백 + 주황 포인트, 01·02 섹션 번호
• designSwitcher: true이면 헤더에 디자인 선택 메뉴가 나타나 방문자가 디자인을 바꿔 볼 수 있습니다. 선택은 그 브라우저에 저장되며(localStorage), 다음 방문 때 깜빡임 없이 적용됩니다. 기본값은 false이고, 끄면 저장된 선택도 무시하고 항상 design 값을 사용합니다.
• profile: 이름, 이니셜, 직함, 소속, 위치, 소개, 이메일, 연구 관심사, SNS 링크, 수정일.
• profile.photo (선택): 프로필 사진. 이미지를 public/에 넣고 "/profile.jpg"처럼 적거나, https:// 주소를 씁니다. 정사각형(최소 320×320px)을 권장합니다. 비워 두면 사진 영역 없이 표시되며, card 디자인에서는 이니셜이 대신 표시됩니다.
• sections: 배열 순서가 화면 표시 순서입니다. 섹션을 추가·삭제·이동할 수 있습니다.
• title: 섹션 제목. cvTitle을 지정하면 CV에서 별도 제목을 사용합니다.
• views: 웹 페이지는 단일 페이지라 모든 섹션을 표시합니다. "cv"가 빠진 섹션은 PDF와 논문 번호 계산에서만 제외됩니다.
• id: 영문 소문자로 시작하는 고유한 소문자·숫자·하이픈 식별자. 이동 링크에 사용됩니다.
• eyebrow: 현재 디자인에서는 표시하지 않습니다(호환용).
• description: 섹션 제목 아래 설명. text는 본문이며 빈 줄 두 개(\n\n)로 문단을 구분합니다.
• profile.updated: 직접 수정하는 최종 수정일입니다.

레이아웃

layout	권장 용도	주요 필드
prose	소개, 연구계획	text
timeline	학력, 경력	items: title, period, organization, description, location
publications	논문, 발표 실적	items: title, authors, venue, year, tag, description, links
cards	연구 프로젝트	items: title, tag, year, description, tags, links
list	수상, 강의, 봉사	items: title, organization, year/period, description, links
tags	기술, 언어, 방법론	items: title, tags
group	자유로운 하위 그룹	children: 섹션 배열, 선택 사항인 text

섹션 제목과 레이아웃은 독립적입니다. 예를 들어 학력을 list로, 수상 내역을 timeline으로 표시할 수 있습니다. group의 children에는 동일한 구조의 섹션을 넣습니다(최대 5단계 중첩). 그룹의 views가 먼저 적용되고 자식의 views가 추가로 적용됩니다.

논문·프로젝트에 실제 링크를 등록하려면 해당 항목에 추가합니다:

"links": [
  { "label": "Paper", "url": "https://doi.org/YOUR-DOI" },
  { "label": "Code", "url": "https://github.com/YOUR-ACCOUNT/YOUR-REPO" }
]

label은 자유롭게 쓸 수 있고, 웹에서는 label에 맞는 아이콘이 자동으로 붙습니다.

label 예시	아이콘
Paper, PDF, arXiv, DOI, OpenReview	문서
Code, GitHub	코드
Project page, Website, Demo	지구본
Video, Talk / Slides / Poster / Dataset / BibTeX / Blog	각각 재생·슬라이드·이미지·데이터·인용·책
그 외	링크

modern 디자인에서는 작은 버튼, editorial 디자인에서는 밑줄 텍스트 링크로 표시됩니다. PDF에서는 한 줄에 Paper · Code · Project page처럼 밑줄 친 클릭 가능한 링크로 들어갑니다.

이 예시 URL은 실제 값으로 바꿔야 합니다. 등록하지 않은 링크는 버튼을 만들지 않습니다. SNS와 링크는 https://, http://, mailto:만 허용합니다. HTML은 렌더링하지 않습니다.

content/portfolio.json을 비롯한 변경을 main 브랜치에 push하면 GitHub Actions가 검증·빌드한 뒤 GitHub Pages에 자동 배포합니다.

2. GitHub Pages로 운영

프로젝트 전체를 원하는 GitHub repository의 main 브랜치에 올립니다. 저장소에서 Settings → Pages → Build and deployment → Source를 GitHub Actions로 선택하면 .github/workflows/deploy-pages.yml이 이후 push마다 실행됩니다.

git remote add origin https://github.com/OWNER/REPOSITORY.git
git push -u origin main

Actions는 다음 순서로 동작합니다.

1. 의존성을 설치합니다.
2. content/portfolio.json을 스키마로 검증합니다.
3. 사이트를 정적 HTML로 빌드합니다.
4. GitHub Pages artifact를 배포합니다.

콘텐츠와 React/CSS 구현 모두 같은 저장소에서 관리하므로 어느 파일을 수정해도 동일한 배포 흐름을 탑니다. 정적 빌드 시 콘텐츠가 포함되므로 private repository에도 별도 PAT나 브라우저 토큰을 둘 필요가 없습니다. 다만 최종 사이트에서 표시되는 내용은 Pages 방문자에게 보이므로 설정 파일에 비밀이나 비공개 메모를 넣지 마세요.

GitHub Free에서는 Pages가 public repository에 제공됩니다. private repository의 Pages 빌드는 GitHub Pro, Team 또는 Enterprise 계정이 필요할 수 있습니다. 저장소가 private이더라도 Pages 사이트 자체는 일반적으로 공개되며, 사이트 접근 제한은 GitHub Enterprise Cloud 조직의 private Pages 기능이 필요합니다.

프로젝트 저장소 이름이 USERNAME.github.io가 아니어도 workflow가 Pages의 base path를 자동으로 빌드에 전달하므로 Home, CV, PDF 폰트 경로가 올바르게 동작합니다.

Google Analytics 4 연결 (선택)

NEXT_PUBLIC_GA_MEASUREMENT_ID를 설정하면 Home과 CV에서 Google Analytics 4(GA4)가 활성화됩니다. 비어 있으면 Google Analytics 스크립트를 로드하지 않습니다. 개발 서버에서는 ID가 있어도 수집하지 않으며, 정식 빌드에서만 활성화됩니다.

1. Google Analytics에서 계정과 GA4 속성을 만들거나 기존 속성을 선택합니다.
2. 관리 → 데이터 스트림 → 웹에서 실제 사이트 주소(예: https://jinhyeonkwon.github.io)로 웹 스트림을 만들고, G-로 시작하는 측정 ID를 복사합니다. 자세한 위치는 Google의 측정 ID 안내를 참고하세요.
3. GitHub 저장소의 Settings → Secrets and variables → Actions → Variables → New repository variable에서 이름을 NEXT_PUBLIC_GA_MEASUREMENT_ID, 값을 복사한 측정 ID로 등록합니다. Secrets가 아닌 Variables에 등록해야 합니다. 측정 ID는 사이트에 공개되는 식별자이며 API 비밀키가 아닙니다.
4. 이 코드 변경을 main에 push한 뒤, Actions → Deploy portfolio to GitHub Pages → Run workflow로 새 빌드·배포를 실행합니다. 변수만 등록·변경하면 자동 배포되지 않습니다. ID는 빌드 결과에 포함되므로 변경하거나 삭제한 경우에도 다시 빌드·배포해야 합니다.
5. 배포된 Home과 CV를 방문한 뒤 Google Analytics의 보고서 → 실시간에서 방문이 표시되는지 확인합니다. 표시되지 않으면 광고 차단 확장 기능을 끄고, Tag Assistant로 측정 ID가 감지되는지 확인합니다.

Google의 gtag.js 설치 방식을 공통 레이아웃에 적용했습니다. 현재 Home/CV 링크는 페이지를 새로 로드하므로 각 방문 시 기본 page_view가 전송됩니다. 별도의 태그나 수동 page_view 코드를 중복으로 붙일 필요가 없습니다. PDF 버튼 클릭 전용 이벤트는 추가하지 않습니다.

로컬에서 정적 빌드 결과를 확인하려면 .env.example을 .env.local로 복사하고 실제 측정 ID를 넣습니다.

cp .env.example .env.local
# .env.local에서 NEXT_PUBLIC_GA_MEASUREMENT_ID=G-실제측정ID 로 수정
npm ci
npm run build:pages
python3 -m http.server 8000 --directory out

http://localhost:8000을 방문하면 이 정식 빌드도 지정한 GA4 속성에 방문을 전송하므로 테스트용 속성을 사용할 수 있습니다. .env.local은 Git에 포함되지 않습니다. 수집을 중단하려면 GitHub 변수를 삭제하거나 로컬 값을 비운 뒤 다시 빌드·배포합니다.

3. CV와 PDF 저장

홈 한 페이지에 전체 논문과 이력이 표시되며, 데스크톱에서는 상단 메뉴로 각 섹션에 바로 이동합니다. PDF 저장은 선택 기능입니다.

논문은 하나의 publications 섹션에 전부 등록하며, 웹과 PDF 모두 전체 논문을 표시합니다(selected는 호환용으로만 남아 있습니다). 섹션 제목은 cvTitle이 있으면 그것을, 없으면 title을 사용합니다.

논문 번호

CV에 표시되는 모든 publications 섹션과 하위 그룹을 합쳐 유형별로 오래된 논문부터 번호를 붙입니다. 홈의 주요 논문과 PDF에도 같은 번호를 사용합니다. CV와 PDF에서는 논문을 연도별로 묶어 최신 연도부터 표시하고, 같은 연도 안에서는 번호가 큰 논문부터 표시합니다. 예를 들어 같은 해의 conference paper는 C03, C02, C01 순서입니다.

publicationType	접두사
conference	C01, C02, …
journal	J01, J02, …
workshop	W01, W02, …
preprint	P01, P02, …
other	O01, O02, …

publicationType을 생략하면 tag의 Conference/Journal/Workshop/Preprint 문자열에서 유형을 추론하고, 해당하지 않으면 O를 사용합니다. 연도는 year, 같은 해의 정확한 순서는 publicationDate에 YYYY-MM-DD 형식으로 지정합니다. 날짜가 없으면 그해 1월 1일로 취급하고 동률은 설정 파일의 순서로 결정합니다. 연도도 없으면 날짜가 있는 항목 뒤에 배치합니다. 새 논문을 추가하면 연대순에 맞춰 번호가 다시 계산됩니다.

PDF 저장

소개 영역의 CV (PDF) 버튼을 누르면 현재 CV 내용으로 PDF 파일을 생성하고 새 탭의 브라우저 PDF 리더에서 먼저 엽니다. 확인 후 PDF 리더의 저장 버튼으로 내려받을 수 있습니다. 팝업 차단이 켜져 있으면 이 사이트의 팝업을 허용해야 합니다. 브라우저 인쇄창을 사용하지 않으며, 사이트 주소·인쇄 날짜·브라우저 머리말과 꼬리말을 넣지 않습니다. A4 문서에 글꼴을 포함하고, 본문은 선택·검색 가능하며 등록한 링크는 클릭할 수 있습니다. 일반 항목은 페이지 중간에서 나누지 않고, 한 페이지보다 긴 항목은 다음 페이지로 이어집니다.

PDF는 브라우저 안에서 생성하며 개인정보를 별도 PDF 서비스에 전송하지 않습니다. sample: true일 때는 예시 문서임을 표시합니다. 실제 제출 전 실제 이력과 링크로 교체한 뒤 sample을 false로 바꾸세요.

웹은 Pretendard를 사용합니다. PDF의 영문은 LaTeX 계열의 Latin Modern, 한글 등은 Pretendard 1.3.9의 OFL 라이선스 파생 글꼴인 Portfolio Sans로 표시합니다. 각 라이선스는 public/fonts/에 포함되어 있고, scripts/prepare-pdf-fonts.py에 한글 글꼴 변환 절차가 있습니다. 이미 변환한 TTF가 포함되어 있어 일반 빌드에는 Python이 필요 없습니다.

4. 구현 수정과 확인

• app/portfolio.tsx: 단일 페이지 화면과 섹션 레이아웃, 테마 토글
• app/globals.css: 기본(modern) 디자인 — 폰트, 라이트/다크 색상 토큰, 반응형 UI
• lib/designs.ts: 디자인 목록, 표시 이름, 디자인별 웹 폰트
• app/designs/*.css: 추가 디자인(editorial, terminal, card, mono-accent). 각각 html[data-design="…"] 범위에서 기본 스타일을 덮어씁니다. 새 디자인은 lib/designs.ts의 designs·designLabels에 이름을 추가하고 CSS 파일을 만들어 app/layout.tsx에서 import합니다.
• app/theme-provider.tsx: 다크 모드(next-themes, 시스템 설정 기본)
• scripts/preview.mjs: 정적 빌드 로컬 미리보기 서버
• lib/schema.ts: 콘텐츠 검증 규칙
• lib/publications.ts: 유형별 논문 번호
• lib/cv-pdf.ts: 인쇄창을 사용하지 않는 PDF 문서 생성
• .github/workflows/deploy-pages.yml: main push 자동 배포
• next.config.ts: GitHub Pages 정적 export와 base path

로컬에서 확인하기

npm ci
npm run dev:local   # http://localhost:3000 — 저장하면 바로 반영되는 개발 서버
npm run preview     # GitHub Pages와 같은 정적 빌드(out/)를 만들어 http://localhost:4173 에서 서빙

설정 파일을 바꾸지 않고 다른 디자인을 미리 보려면 SITE_DESIGN 환경 변수로 덮어씁니다: SITE_DESIGN=editorial npm run dev:local.

dev:local은 content/portfolio.json, CSS, 컴포넌트를 수정하는 즉시 브라우저에 반영됩니다. 배포 직전에는 preview로 실제 산출물을 확인하세요(npm run preview -- --no-build는 빌드 없이 기존 out/만 서빙). 두 명령 모두 Node 20에서도 동작합니다.

기타 검증

node --experimental-strip-types --test tests/publications.test.ts
npx tsc --noEmit
npm run build:pages

개발 환경은 Node 22.13 이상이 필요합니다. npm run build는 기존 Sites 호스팅 호환 빌드이고, GitHub Pages용 산출물은 npm run build:pages로 out/에 생성합니다.