[Github] ReadMe 작성시 고려사항과 Markdown

github 저장소를 소개하는 readme 작성시 필요한 내용을 정리했다.
readme 작성은 중요하지만 개발 생각만 하는 순간 간과하게 되는 부분인 것 같다. 대부분의 깃헙을 잘 관리하는 개발자들은 readme의 중요성을 이야기하고 있고 나 역시 놓치고 싶지 않은 부분이라고 생각되서 블로그에 정리하면서 주의하고자 한다.

 

 

반드시 들어가야 한다고 생각하는 부분(1~3번 항목) 크게 나누면 아래와 같다.

 

 

1. 프로젝트 계획 이유와 프로젝트에 대한 설명(Description)

github에 오픈소스로 코드를 올리면서 또는 협업을 위해 다른 개발자들도 내 저장소를 보기 때문에 저장소에 대한 소개는 반드시 필요하다. 어떤 내용을 담고 있는지, 간결하면서 직관적으로 작성할 필요가 있다.

 

2. 기능 설명

1번에서 간단한 설명이 끝났다면, 구체적인 기능을 간략하게 나열하는 것이 좋다. 가령 API 저장소라면 포함된 API들이 어떤 기능과 서비스를 제공하는지 작성한다.

 

3. 개발환경과 실행방법 

개발에 사용된 OS, Language, Framework, Middleware, Compiler 등을 작성한다. 개발환경은 정말 다양하기 때문에 코드 참조시 도움이 되는 자료이다. 필요시 협업하는 개발자가 코드를 저장받아 각자 컴퓨터에서 개발환경을 구축하는데 필요한 요소이다. 

 

4. (필요한 경우) 라이선스(License)

깃헙의 코드가 퍼블릭 저장소인 경우, 오픈소스로 다른 개발자가 사용할 수 있다. 따라서 불필요한 복제품 생산을 막고 싶은 서비스의 경우, 라이선스 표시를 github에 할 수 있다. 

 

+ Badge

readme에는 배지를 사용할 수 있는데, https://shields.io/ 사이트에서 보면, suggest badges를 이용해서 readme를 꾸밀 수 있다.

 

---

 

이제 readme 작성시 알아야할 markdown에 대해 알아보자.

 

1. 아무런 기호 없이 입력하는 경우

>> 입력된 텍스트가 그대로 보인다.

 

2. 제목입력을 위한 #

>> 글의 앞부분에 #를 입력한 경우 <h> 태그와 같은 효과를 보인다. #의 개수가 많으면 크기가 작은 소제목이 된다.  최대 6개까지 #를 연속해서 사용할 수 있다.

---

# 제목입력 예시입니다.

## 제목입력 예시입니다.

### 제목입력 예시입니다.

#### 제목입력 예시입니다.

##### 제목입력 예시입니다.

###### 제목입력 예시입니다.

---

제목입력 예시입니다.

제목입력 예시입니다.

제목입력 예시입니다.

제목입력 예시입니다.

 

제목입력 예시입니다.

 

제목입력 예시입니다.

 

 

 

3. 코드블럭 만들기

>> 코드블럭은 tab 을 이용하거나 앞뒤로 ''' 를 사용해서 만들 수 있다.

---

코드블럭 예시입니다.

    코드블럭 예시입니다.

코드블럭 예시입니다.

 

'''

코드블럭 예시입니다.

'''

---

코드블럭 예시입니다.

코드블럭 예시입니다.

코드블럭 예시입니다.

 

코드블럭 예시입니다.

 

 

4. BlockQuote 만들기

>> BlockQuote를 만들기 위해서는 > 기호를 사용한다. 겹쳐서 사용이 가능하다.

---

> BlockQuote 예시입니다.

---

BlockQuote 예시입니다.

 

 

5. 글머리 기호 만들기

>> + , * , -  기호 모두 같은 출력을 불러오는 것을 알 수 있다. tab 을 이용해서 위계 문단을 구별할 수 있다.

---

+ 글머리 기호

    + 글머리 기호

        + 글머리 기호

---

 

6. 수평선 만들기

>> 문단을 구분하기 위해 - 를 연속해서 사용하므로써 <hr>과 같은 역할의 수평선을 만들 수 있다.

---

---------------------------------

---

---

 

 

 

 

 

---

README 작성 가이드

[Git, 깃] README.md 작성하는 방법, 예시 | markdown (마크다운) 사용법, 문법 : 네이버 블로그

[Markdown] 웹 개발자를 위한 README.md 작성법

Readme.md badge : 네이버 블로그