← 블로그

GitHub README 잘 작성하는 법

·4 min read
GitHubREADME마크다운오픈소스

GitHub README 잘 작성하는 법

GitHub 저장소에 처음 방문했을 때 가장 먼저 보이는 것이 README 파일입니다. README는 프로젝트의 얼굴이자 문서의 시작점입니다. 아무리 훌륭한 코드라도 README가 부실하면 사람들이 사용하지 않습니다. 이 글에서는 효과적인 README를 작성하는 방법을 실제 예시와 함께 알아보겠습니다.

README가 중요한 이유

README는 단순한 설명서가 아닙니다. 프로젝트에 대한 다양한 역할을 수행합니다.

  • 첫인상: 방문자가 프로젝트를 이해하고 관심을 갖는 첫 번째 접점입니다.
  • 사용 설명서: 프로젝트를 어떻게 설치하고 사용하는지 안내합니다.
  • 기여 안내: 오픈소스 기여자에게 참여 방법을 알려줍니다.
  • 신뢰도: 잘 정리된 README는 프로젝트의 품질을 간접적으로 보여줍니다.
  • 검색 최적화: GitHub 내 검색에서 README 내용이 인덱싱됩니다.

README의 기본 구조

좋은 README는 다음과 같은 구조를 갖추고 있습니다.

1. 프로젝트 제목과 한 줄 설명

# 프로젝트 이름

> 프로젝트가 무엇인지 한 문장으로 설명합니다.

한 줄 설명만 읽어도 이 프로젝트가 무엇을 하는지 이해할 수 있어야 합니다.

2. 배지 (Badges)

프로젝트의 상태를 한눈에 보여주는 배지를 추가합니다.

![Build Status](https://img.shields.io/github/actions/workflow/status/user/repo/ci.yml)
![License](https://img.shields.io/github/license/user/repo)
![npm version](https://img.shields.io/npm/v/package-name)
![Downloads](https://img.shields.io/npm/dm/package-name)

shields.io에서 다양한 배지를 생성할 수 있습니다. 다만 배지를 너무 많이 넣으면 오히려 지저분해질 수 있으니 핵심적인 것만 선택하세요.

3. 스크린샷 또는 데모

텍스트보다 이미지가 훨씬 빠르게 프로젝트를 이해시킵니다.

## 스크린샷

![메인 화면](./docs/images/screenshot-main.png)

## 데모

[라이브 데모 보기](https://demo.example.com)

GIF를 활용하면 동적인 기능을 보여줄 수 있습니다. 단, 파일 크기가 너무 크지 않도록 주의하세요.

4. 주요 기능

프로젝트의 핵심 기능을 목록으로 정리합니다.

## 주요 기능

- 마크다운 파일을 PDF로 변환
- 실시간 미리보기 지원
- 커스텀 CSS 테마 적용
- 한글 폰트 완벽 지원
- 코드 구문 강조

5. 설치 방법

명확하고 따라하기 쉬운 설치 안내를 제공합니다.

## 설치

### 필수 조건

- Node.js 18 이상
- npm 또는 yarn

### 설치 방법

```bash
# npm으로 설치
npm install my-package

# 또는 yarn으로 설치
yarn add my-package
```

6. 사용법

설치 후 어떻게 사용하는지 구체적인 예시를 보여줍니다.

## 사용법

### 기본 사용

```javascript
import { convert } from 'my-package';

const result = convert('# Hello World');
console.log(result);
```

### 고급 설정

```javascript
const options = {
  theme: 'dark',
  fontSize: 14,
  language: 'ko',
};

const result = convert(content, options);
```

코드 예시는 복사-붙여넣기만으로 바로 실행할 수 있도록 작성하는 것이 좋습니다.

7. API 문서 (라이브러리인 경우)

## API

### `convert(markdown, options?)`

마크다운 문자열을 HTML로 변환합니다.

| 매개변수 | 타입 | 기본값 | 설명 |
|----------|------|--------|------|
| markdown | string | - | 변환할 마크다운 문자열 |
| options | object | {} | 변환 옵션 |
| options.theme | string | 'light' | 테마 설정 |

8. 기여 가이드

## 기여하기

기여를 환영합니다! 다음 단계를 따라주세요.

1. 이 저장소를 Fork합니다.
2. 기능 브랜치를 만듭니다. (`git checkout -b feature/amazing-feature`)
3. 변경사항을 커밋합니다. (`git commit -m 'Add amazing feature'`)
4. 브랜치에 푸시합니다. (`git push origin feature/amazing-feature`)
5. Pull Request를 생성합니다.

자세한 내용은 [CONTRIBUTING.md](CONTRIBUTING.md)를 참고하세요.

9. 라이선스

## 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 [LICENSE](LICENSE) 파일을 참고하세요.

README 작성 팁

독자를 생각하라

README를 읽을 사람은 크게 세 부류입니다:

  1. 프로젝트를 처음 본 사람: 이게 뭔지 빨리 알고 싶음
  2. 사용하고 싶은 사람: 설치와 사용법이 필요함
  3. 기여하고 싶은 사람: 개발 환경 셋업과 기여 방법이 필요함

세 부류 모두를 만족시키는 구조로 작성해야 합니다.

목차를 추가하라

README가 길어지면 목차를 추가합니다.

## 목차

- [설치](#설치)
- [사용법](#사용법)
- [API](#api)
- [기여하기](#기여하기)
- [라이선스](#라이선스)

간결하게 쓰라

README는 매뉴얼이 아닙니다. 핵심 정보만 담고, 상세한 내용은 별도 문서로 분리하세요.

자세한 사용법은 [공식 문서](https://docs.example.com)를 참고하세요.

최신 상태를 유지하라

오래된 README는 없는 것보다 나쁩니다. 코드가 바뀌면 README도 함께 업데이트하세요. CI에서 README의 코드 예시를 자동으로 테스트하는 것도 좋은 방법입니다.

좋은 README 예시 분석

실제로 잘 작성된 오픈소스 프로젝트의 README를 분석해보겠습니다.

공통점

  1. 명확한 한 줄 설명: 프로젝트가 무엇인지 즉시 파악 가능
  2. 시각적 요소: 로고, 스크린샷, GIF 등으로 이해를 도움
  3. 빠른 시작: 5분 안에 프로젝트를 실행해볼 수 있는 가이드
  4. 사용 예시: 실제 코드로 보여주는 사용법
  5. 친절한 기여 안내: 기여 방법이 명확하게 안내됨

README 템플릿

아래 템플릿을 기반으로 프로젝트에 맞게 수정하면 됩니다.

# 프로젝트 이름

> 한 줄 설명

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

## 소개

프로젝트에 대한 간단한 설명 (2-3문장)

## 주요 기능

- 기능 1
- 기능 2
- 기능 3

## 빠른 시작

## 설치

## 사용법

## 문서

## 기여하기

## 라이선스

README를 PDF로 만들기

프로젝트 제안서나 포트폴리오에 README를 포함해야 할 때가 있습니다. 이럴 때 printmd를 사용하면 마크다운 README를 깔끔한 PDF 문서로 변환할 수 있습니다. 코드 블록의 구문 강조도 유지되고, 표도 깔끔하게 렌더링됩니다.

마무리

좋은 README는 하루아침에 완성되지 않습니다. 프로젝트가 발전하면서 README도 함께 성장해야 합니다. 처음에는 기본 구조만 갖추고, 사용자의 질문이나 피드백을 반영해 계속 개선해나가세요. README를 잘 쓰는 것은 결국 사용자를 배려하는 것이고, 그것이 좋은 오픈소스 프로젝트의 시작입니다.

printmd로 마크다운을 PDF로 변환해보세요

printmd 시작하기