GitHub README Stats가 보여 주는 것
GitHub README Stats는 사용자 이름으로 SVG 카드를 생성합니다. 기본 카드에는 별, 커밋, 풀 리퀘스트, 이슈, 기여 저장소와 랭크 등을 표시할 수 있고 별도 카드로 주요 언어 비율도 보여 줍니다.
이 수치는 개발 역량 전체를 평가하지 않습니다. 저장소 공개 범위, 비공개 활동, fork, 생성 파일, 캐시와 API 제한에 따라 값이 달라질 수 있습니다. 카드는 빠른 안내로 사용하고 성과 점수처럼 해석하지 않아야 합니다.
카드는 소개나 대표 프로젝트 뒤에 배치하세요. 목적에 따라 Streak Stats 가이드, Trophy 가이드, README 템플릿, GitHub City를 연결할 수 있습니다.
카드는 대화를 시작하지만 프로젝트가 근거를 제공합니다. 해결한 문제, 담당 역할, 기술적 선택과 확인할 수 있는 코드를 설명하세요.
통계 카드 추가와 설정 방법
가장 단순한 URL로 먼저 확인한 뒤 옵션을 하나씩 추가하면 잘못된 설정을 쉽게 찾을 수 있습니다.
프로필 README 열기
사용자 이름과 정확히 같은 공개 저장소의 README에 카드 코드를 넣고 소개나 프로젝트 아래에 배치합니다.
사용자 이름 확인
공식 URL의 username 값을 바꾸고 이미지 주소를 직접 열어 정상 표시를 확인합니다.
읽기 쉬운 테마 선택
실제 README 배경에서 명암 대비를 확인하고 화려한 위젯을 여러 개 겹치지 않습니다.
의미 있는 옵션만 사용
아이콘이나 숨김 설정은 독자의 이해를 높일 때만 적용합니다.
어떤 프로필 시각화를 선택할까
각 요소가 답하는 질문은 다릅니다. 기본 시각화 하나와 보조 요소 하나면 충분합니다.
| 시각화 | 적합한 목적 | 설정 | 한계 | 배치 |
|---|---|---|---|---|
| 통계 카드 | 활동 전체 요약 | 사용자 URL | 맥락 필요 | 소개 뒤 |
| 주요 언어 카드 | 언어 구성 | 별도 카드 | 실력 순위 아님 | 통계 카드 근처 |
| Streak Stats | 최근 꾸준함 | 전용 서비스 | 매일 활동을 과도하게 강조 | 필요할 때만 |
| GitHub City | 3D 기여 달력 탐색 | 브라우저 도구 | 프로젝트 증거 대체 불가 | 자세한 링크 |
자주 발생하는 문제
대부분 사용자 이름, URL, 서비스 상태, 공개 범위 또는 지표 해석에서 문제가 생깁니다.
카드가 표시되지 않음
이미지 URL을 직접 열고 사용자와 옵션을 확인한 뒤 설정을 제거하며 공식 저장소 상태를 봅니다.
수치가 예상보다 낮음
대상 저장소, 비공개 활동, fork, 캐시와 API 제한을 확인합니다.
테마가 읽기 어려움
실제 배경에서 테스트하고 대비가 낮은 투명 조합을 피합니다.
언어 비율이 부정확해 보임
생성 코드, Notebook 또는 큰 저장소가 비율을 지배할 수 있습니다.
위젯보다 작업 증거를 중심에 두기
좋은 프로필은 누구인지, 무엇을 만들었는지, 어떤 코드를 볼지 먼저 설명합니다. 프로젝트와 결과가 통계보다 앞에 와야 하며 카드 한 장은 도움이 되지만 여러 장은 집중을 방해합니다.
전체 구조는 README 템플릿 가이드로 정리하고 GitHub City는 기여 기록을 입체적으로 탐색하는 추가 링크로 사용하세요.
데스크톱과 모바일 너비에서 README를 확인하고 같은 신호를 반복하는 카드와 너무 넓은 행을 줄이세요.
추천 구성
짧은 소개, 대표 프로젝트 2~3개, 통계 카드 한 장, 필요한 경우 보조 시각화 한 개를 사용하고 나머지는 설명형 링크로 둡니다.
자주 묻는 질문
GitHub 공식 기능인가요?
아닙니다. 프로필 README는 GitHub 기능이지만 카드 생성 서비스는 별도의 오픈 소스 프로젝트입니다.
README에 통계를 어떻게 추가하나요?
프로필 저장소 README에 사용자 이름이 들어간 이미지 Markdown을 추가하고 미리 보기로 확인합니다.
비공개 커밋이 왜 빠지나요?
공개 설정, API에서 제공하는 데이터와 서비스 설정에 따라 표시 범위가 달라집니다.
Stats, Streak, Trophy 중 무엇을 쓰나요?
전체 요약은 Stats, 꾸준함은 Streak, 이정표는 Trophy가 적합합니다. 목적에 맞게 고르세요.
GitHub City와 함께 쓸 수 있나요?
네. 카드는 요약을 제공하고 GitHub City는 기여 달력을 3D로 자세히 보여 줍니다.