Gemini Kim의 한국어·영어 개인 기술 블로그입니다. Astro로 정적 생성되며, 모든 글과 번역본은 Markdown으로 작성합니다.
Node.js 24 이상과 npm이 필요합니다.
npm install
npm run dev개발 서버는 기본적으로 http://localhost:4321에서 실행됩니다.
npm run check # Astro/TypeScript 검사
npm run build # 검사 후 정적 사이트 생성
npm run verify:i18n # 빌드된 다국어 URL·SEO 계약 검사
npm run preview # 생성 결과 미리 보기src/content/blog/ko/ 또는 src/content/blog/en/ 아래에 .md 파일을 추가합니다. 언어 폴더 다음의 파일 경로가 글의 URL slug가 됩니다.
---
title: "글 제목"
description: "목록과 검색 결과에 표시할 짧은 설명"
lang: ko
translationKey: stable-article-id
publishedAt: 2026-07-27
updatedAt: 2026-07-28 # 선택
tags:
- astro
- engineering
draft: false
---
Markdown으로 본문을 작성합니다.title,description,lang,translationKey,publishedAt은 필수입니다.lang은ko또는en입니다.- 같은 글의 한국어·영어 번역본은 동일한
translationKey를 사용합니다. updatedAt은 글을 의미 있게 수정했을 때 추가합니다.tags는 문자열 배열이며 생략하면 빈 배열로 처리됩니다.draft: true인 글은 개발 서버에서는 보이지만 프로덕션 빌드에서는 제외됩니다.
- 영어가 기본 언어이며
/,/articles/,/about/을 사용합니다. - 한국어는
/ko/,/ko/articles/,/ko/about/아래에 생성됩니다. - 기존
/en/과/en/about/은 같은 영어 기본 경로로 이동하는 호환 리다이렉트입니다. - 헤더의
KO / EN선택은localStorage의geminikim.locale에ko또는en만 저장합니다. - 저장된 선택이 없으면 홈페이지에서만 브라우저 언어를 확인합니다. 한국어 브라우저는
/ko/로 이동하고 그 외 언어는 영어/를 유지합니다. - 글 상세 주소를 직접 열었을 때는 브라우저 언어로 강제 이동하지 않습니다.
- 언어별 페이지에는 canonical 및
hreflang메타데이터가 생성됩니다.x-default는 영어 기본 URL입니다. - 영어와 한국어 RSS는 각각
/rss.xml,/ko/rss.xml에서 제공합니다. 기존/en/rss.xml도 호환용으로 유지합니다.
.github/workflows/deploy.yml이 main 브랜치로의 push를 감지해 GitHub Pages에 배포합니다.
저장소의 Settings → Pages → Build and deployment → Source를 GitHub Actions로 설정해야 합니다. 이후 Actions의 Deploy to GitHub Pages 워크플로가 빌드와 배포를 담당합니다.
이 저장소는 사용자 사이트(geminikim.github.io)이므로 별도의 Astro base 경로를 사용하지 않습니다.
이 저장소는 공개 저장소입니다. 액세스 키, API 키, 비밀번호, 토큰, 개인 키, 인증서 및 실제 환경설정 값은 커밋하지 않습니다. 로컬 환경 파일과 일반적인 자격증명 파일은 .gitignore에서 제외합니다. GitHub Actions에도 별도 비밀값을 사용하지 않으며, Pages 배포에 필요한 최소 권한만 선언합니다.
src/
├── components/ # Header, Footer, 글 목록, 언어 선택
├── content/blog/ # ko/en 언어별 Markdown 글
├── i18n/ # 지원 언어와 공통 UI 문구
├── layouts/ # 공통 문서 레이아웃과 다국어 메타데이터
├── lib/ # 언어별 글 조회와 날짜 포맷
├── pages/ # 영어 기본 경로, /ko 한국어, /en 호환 리다이렉트
└── styles/ # 다크 전용 전역 스타일