마크다운(.md 파일) 문서 작성법 | README.md, CHANGELOG.md

 

 

---

개요

프로젝트를 개발하다 보면 코드 못지않게 중요한 것이 바로 문서화입니다. 특히 Git 기반 프로젝트에서는.md 문서로 프로젝트의 품질을 높힐 수 있습니다. 특히 깔끔한 README.md와 체계적인 CHANGELOG.md를 갖춘 프로젝트는 신뢰감을 주고, 협업이나 오픈소스 기여도 훨씬 쉬워집니다.
이 글에서는 마크다운 문서 중에서도 README.md와 CHANGELOG.md의 역할과 작성 요령에 대하여 정리해보겠습니다.

 

마크다운(Markdown) 문서란?

마크다운(Markdown)은 텍스트 기반의 경량 마크업 언어로 간단한 문법만으로 HTML처럼 문서의 구조를 표현할 수 있는 형식입니다.

.md 확장자를 가지며, 개발자 문서, 블로그, README 등 다양한 곳에서 널리 사용됩니다.

• README.md – 프로젝트 소개 및 설명
• CHANGELOG.md – 버전별 변경 기록
• CONTRIBUTING.md – 오픈소스 기여 가이드
• 블로그 포스팅 – Velog, Hugo, Jekyll 등

 

마크다운 특징

항목	설명
간단한 문법	복잡한 태그 없이 #, -, * 등으로 문서 구조 표현 가능
가독성 좋음	마크다운으로 작성된 원문 자체도 읽기 쉽고 깔끔함
HTML 변환 용이	마크다운 문서는 HTML로 쉽게 변환됨
다양한 지원 환경	GitHub, Notion, VSCode, 블로그 플랫폼 등 대부분의 개발 도구에서 지원

 

마크다운 기본 문법 정리

	문법	출력 결과
제목	# 제목1 ## 제목2	제목1 제목2
굵은 글씨	**굵게** or __굵게__	굵게
기울임	*기울임* or _기울임_	기울임
취소선	~~취소선~~	취소선
리스트	- 항목 * 항목	- 항목 - 항목
번호 리스트	1. 항목 2. 항목	1. 항목 2. 항목
링크	[Google](https://google.com)	Google
이미지		(이미지)
인라인 코드	`코드`	코드
코드 블록	<pre>js<br>console.log()<br></pre>	js<br>console.log()<br>
인용문	> 인용문	> 인용문
수평선	--- or ***	――――――――
체크박스	- [ ] 할 일 - [x] 완료	☐ 할 일 ☑ 완료
표 만들기	<pre>|헤더1|헤더2| |--|--|</pre>	표 형태로 출력됨

 

 

 

README.md

README.md는 프로젝트의 소개, 설치 방법, 사용법 등을 담는 문서입니다. 이 문서는 GitHub, GitLab과 같은 플랫폼에서 리포지토리의 첫 화면에 노출되어 프로젝트의 첫인상을 결정짓는 파일입니다. 

 

README.md 주요 작성 항목

프로젝트 개요

프로젝트의 목적과 기능 설명

 

설치 방법

사용자 환경에 프로젝트를 설치하는 방법

 

사용 예제

주요 기능을 간단히 시연하는 코드나 설명

 

기여 가이드

다른 개발자가 프로젝트에 기여할 수 있는 방법

 

라이선스

프로젝트 사용 시 적용되는 라이선스 정보

 

예시)

## 프로젝트 개요
이 프로젝트는 OOO 문제를 해결하기 위해 개발되었으며, 다음과 같은 기능을 제공합니다
- 기능 A
- 기능 B

## 설치 방법
```bash
# 1. 저장소 클론
git clone https://github.com/username/project.git

# 2. 디렉토리 이동
cd project

# 3. 패키지 설치
npm install
```

---

### 사용 예제 (Usage)  
> 주요 기능을 보여주는 코드 또는 실행 예제를 제공합니다.
```js
import { doSomething } from 'project';

doSomething('Hello World!');
```

---

### 기여 가이드 (Contributing)  
> 다른 개발자가 프로젝트에 기여할 수 있는 방법을 안내합니다.  
브랜치 전략, PR 규칙, 코드 스타일 등 포함 가능
   
## 라이선스
MIT License를 따릅니다. 자세한 내용은 [LICENSE](./LICENSE) 파일을 참고하세요.

 

CHANGELOG.md

CHANGELOG.md는 프로젝트의 변경 이력을 기록하는 문서입니다.
주로 새 릴리스 시 추가된 기능, 수정된 사항, 버그 수정 등을 명확하게 정리하여 사용자와 개발자 모두가 변경 사항을 쉽게 파악할 수 있도록 도와줍니다.

 

CHANGELOG.md 주요 작성 항목

추가 (Added)

새로 추가된 기능이나 파일

 

변경 (Changed)

기존 기능의 수정 또는 개선 사항

 

제거 (Removed)

삭제되거나 더 이상 사용되지 않는 기능

 

버그 수정 (Fixed)

해결된 오류나 버그

 

CHANGELOG.md 작성 규칙

버전 정보 명시
각 릴리스 항목에는 반드시 버전 번호와 릴리스 날짜를 포함합니다.

 

명확한 카테고리 구분이 되어야 합니다.
변경 사항은 "Added", "Changed", "Fixed", "Removed" 등으로 구분해 작성합니다.

 

일관된 포맷 유지
팀 내에서 변경 기록 포맷을 정해두고, 동일한 규칙을 따르도록 합니다. (예: 날짜 포맷, 제목 스타일, 정렬 순서 등)

 

예시)

# Changelog

## [1.2.0] - 2025-04-11

### Added
- 사용자 알림 기능 추가
- 다국어 지원 (한국어/영어)

### Changed
- 로그인 로직 리팩토링
- UI 일부 개선

### Fixed
- 비밀번호 변경 시 오류 발생 문제 해결

## [1.1.0] - 2025-03-01

### Added
- 관리자 대시보드 페이지 추가

### Removed
- 구버전 API 제거

 

README.md, CHANGELOG.md 비교

구분	README.md	CHANGELOG.md
목적	프로젝트 소개 및 사용법 제공	릴리스 변경 사항 기록
대상	프로젝트를 처음 접하는 사용자	기존 사용자 및 개발자
내용	개요, 설치 방법, 사용 예제 등	기능 추가, 변경, 제거, 버그 수정 등