Readme.md 파일 작성법

이번 포스팅에서는 여러분들의 Github Repository를 한층 업그레이드 시킬 수 있는 Readme.md 파일 작성법에 대해서 알아보겠습니다.

1. README

1) 개념

README 파일은 주로 Github 프로필 혹은 Repository에 대한 설명을 나타내기 위해 작성한다. README는 쉽게 말하면 가이드라인, 안내문 정도로 생각할 수 있다. 그 이유는 README 파일에는 일반적으로 프로젝트에 대한 정보가 담겨 있어, 소프트웨어 배포시에 함께 포함되는데, 이러한 점이 마치 새 제품을 샀을 때 읽어보는 사용 설명서와 비슷하기 때문이다.

2) 확장자

우리가 흔히 Readme.md라고 말하는 .md라는 확장자는 Git에서만 사용하는 것이고, Windows 또는 Mac OS에서는 .txt를 확장자로 사용한다. 여기서 md는 마크다운의 약자로 마크다운 문법을 사용한다는 의미이다. 이전에 issue 템플릿을 작성할 때 사용한 언어가 바로 마크다운 언어인데, README 파일을 작성할 때에도 이 마크다운 언어를 사용한다. 사실 멀리갈 것도 없이 벨로그에서 작성하는 파일도 마크다운 언어 형식을 따르고 있다.

※ MarkUp Language & MarkDown Language
마크업 언어란, 문서가 화면에 표시되는 형식을 나타내거나 데이터의 논리적인 구조를 명시하기 위한 규칙들을 정의하는 언어이다. 즉, 어떤 데이터에 대해 가공이나 연산 작업을 수행하는 것이 아니라 그저 데이터를 화면에 표시하기 위해 사용하는 언어라는 뜻이다. 이러한 점에서 프로그래밍 언어와 차이점을 보인다. "HTML은 프로그래밍 언어가 아니다"라는 이야기가 나오는 것도 이러한 이유에서이다.
마크다운 언어는 마크업 언어에서 파생되었지만, 태그를 사용하지 않는다는 점에서 차이가 있다. 읽고 쓰기 쉬운 문서 양식을 지향하기 때문에 간단한 문법만 숙지하면 누구나 쉽게 작성할 수 있다.

3) README 파일의 필요성

README 파일을 작성해야 하는 이유는 무엇일까? 3가지의 이유로 간단하게 정리해보았다.

① For Myself

• 자신이 코딩한 프로그램이라고 해서 언제까지나 코드의 모든 내용을 이해하고 있을 수는 없다.
• 시간이 흘러 자신의 프로그램을 다시 읽어보고 해석해야 할 일이 생길 경우, README 파일이 필요한 수고를 덜어줄 수 있다.

② For My Co-workers

• 함께 협업하는 동료들에게 지침서 역할로 유용하게 쓰일 수 있다.

③ For Users

• 서비스를 구현하여 오픈소스로 배포하는 경우, 자신의 프로그램을 이용하는 사람들이 쉽게 프로그램을 이해할 수 있게 된다.

4) README 파일의 구성

README 파일을 작성하는 방법에 있어 정해진 양식은 하나도 없다. 어떤 구성요소를 포함할지 모르겠다면 아래의 내용을 고려해볼 수 있다.

• 프로젝트 구성
• 프로젝트 프로그램 설치방법
• 프로젝트 프로그램 사용법
• 저작권 및 사용권 정보
• 프로그래머 정보
• 버그 및 디버그
• 참고 및 출처
• 버전 및 업데이트 정보
• FAQ

위와 같이 너무 딱딱한 형식이 싫다면, 프로젝트 소개, 개발 기간, 개발자 소개(역할분담 상세), 개발환경, 기술스택, 주요기능, 프로젝트 아키텍쳐 등을 포함하여 작성할 수도 있다.

확장자 역시 정해져있는 것은 아니고 다양한 형식을 사용할 수 있다. 다만, 일반적으로 .md 확장자를 사용할 것을 권장한다.

2. MarkDown 문법

README 파일을 작성하려면 마크다운 문법은 필수로 알아야한다. 하지만, 위에서 설명한 것처럼 마크다운 문법은 매우 쉽기 때문에 한번만 보고도 바로 숙지할 수 있을 것이다.

1) 제목

#의 개수로 제목의 크기를 조절할 수 있다. #이 적을수록 제목의 글자는 커지고, #이 많을수록 제목의 크기는 작아진다. 총 1~6단계까지 조절 가능하다.

2) 줄바꿈

엔터를 한번만 눌러서는 줄바꿈이 되지 않는다. new line으로 줄바꿈하려면 엔터를 두번 눌러 아래와 같이 공백을 만들어주어야 한다.

3) 구분선

구분선을 추가하기 위해 하이픈(-) 또는 별(*)을 사용할 수 있다. 3개 이상만 적으면 구분선으로 인식한다.

4) 인덱싱

"1." 을 작성하고 엔터를 치면 순차적으로 번호가 자동생성된다.

5) 불릿

인덱싱과 비슷한 용도로 사용되지만, 순서가 중요하지 않은 경우 불릿을 사용한다. 불릿을 나타내기 위해서는 +,-,* 을 사용 가능하다. 탭을 누른 후 불릿을 나타내면 흰 불릿으로 들여쓰기된다.

6) 텍스트 강조

** 또는 __를 문장의 앞뒤를 감싸주면 Bold체가 된다. 만약 * 또는 _로 앞뒤를 감싸주면 Italic체가 되고 *** 또는 ___로 감싸면, Bold+Italic체가 적용된다. ~~로 앞뒤를 감싸면 취소선이 된다.

7) 인용구

> 를 사용하여 인용문을 작성할 수 있다. 또한 >> 처럼 인용 안에 인용문을 추가로 작성할 수도 있다.

8) 하이퍼링크

<> 안에 링크 주소를 넣으면 하이퍼링크가 된다. 또는 [] 안에 링크의 이름을 넣고 () 안에 링크 주소를 넣는 방식으로 하이퍼링크의 이름을 지정해줄 수도 있다. 또한 () 안에 링크 주소와 함께 구분자 콤마를 사용하여 부연설명을 넣을 수도 있다. 여기서 부연 설명이란, 하이퍼링크에 마우스를 갖다 대었을 때 보이는 값이다.

9) 이미지

이미지에 대한 링크 주소가 필요하기 때문에 일반적으로 깃허브 Repository에 사진을 업로드하는 방식을 사용한다. Readme 파일을 작성하려는 Repository에서 Upload files를 클릭해 이미지를 업로드한 후 Commit changes 버튼을 클릭하면 된다.

그 후 업로드된 이미지에 우클릭 > 링크 주소 복사 버튼을 클릭한다.

Readme 파일로 돌아와서  방식으로 작성하면 이미지 첨부가 완료된다.

3. README 파일 작성 방법

① README 파일을 작성할 Repository로 이동한 후 아래에 보이는 Add a README 버튼을 클릭한다. 만약 Repository를 생성할 때 README 파일을 같이 생성한 경우 연필버튼만 누르면 된다.

② Edit 모드에서는 마크다운 문법으로 작성된 글이 보이고, Preview 모드에서는 미리보기 형식의 파일이 보인다.

③ 아래와 같이 Edit 모드에 글을 작성하면 Readme.md 파일이 완성된다.

④ 아래의 링크에서 완성된 모습을 확인할 수 있다.
>> 깃허브 링크

[이미지 출처]

• https://blog.naver.com/ycpiglet/222307838439