C# :: For Beginners VB :: For Beginners

[TIP] Markdown 을 이용한 ReadMe 문서 작성법

안녕하세요? HappyBono 입니다.

이번 게시글에서는 README.md 파일이 무엇인지에 대해 간단하게 설명하고, 여러가지 다양한 형태의 README 파일을 전부 다루는 것 보다는 현재 사용중인 Visual Studio Team Services 에서 지원하는 READMD.md 파일을 위주로 필요한 문법들을 알아보는 시간을 가져보도록 하겠습니다.

기본적으로, README.md 파일은 VSTS, Git, GitHub 등과 같이 코드 저장소 (Repository) 에서 많이 등장하는 파일입니다. 해당 파일은 소스코드에 앞서 어떠한 목적으로 프로젝트가 개발이 되었는지에 대한 프로젝트의 목표를 포함해 코드의 개요나 구조도 등을 사용자에게 노출시킴으로서, 해당 프로젝트에 대한 설명이 담긴 파일입니다.

 

README 란 무엇인가요?

README (readme, read me) 파일은 일반적으로 디렉토리나 압축 파일에 포함된 기타 파일에 대한 정보를 포함하고 있으며, 일반적으로 소프트웨어와 함께 배포됩니다. 또한 현재 Git 과 같은 코드 저장소에서도 해당 파일을 기본값으로 생성되게 하여 해당 저장소에 대한 설명을 기입하도록 유도하고 있습니다.

README 의 파일 확장자는 README.txt, README.md, README.1st, README.doc Read.me 등 다양한 파일명과 확장자의 형태로 작성되고 있습니다.

README 는 다음 중 하나 이상의 정보를 포함합니다 :

  1. 컴퓨터 구성 / 필수 조건 안내 (Prerequisites)
  2. 설치 안내 (Installation Process)
  3. 사용법 (Getting Started)
  4. 파일 정보 및 목록 (File Manifest)
  5. 저작권 및 사용권 정보 (Copyright / End User License)
  6. 배포자 및 개발자의 연락처 정보 (Contact Information)
  7. 알려진 버그 (Known Issues)
  8. 문제 발생에 대한 해결책 (Troubleshooting)
  9. 크레딧 (Credit)
  10. 업데이트 정보 (Change Log)

 

앞서 나열한 목록들 이외에도 필요한 정보들을 추가적으로 포함할 수 있습니다. 추가적으로 오픈소스 배포판을 기준으로 아래와 같은 표준 집합의 README 파일들을 포함합니다.

  1. README : 일반 정보
  2. AUTHORS : 제작 정보
  3. THANKS : 도와주신 분들에 대한 정보
  4. ChangeLog : 개발자들이 참고 할 수 있는 자세한 업데이트 정보
  5. NEWS : 사용자들이 참고 할 수 있는 자세한 업데이트 정보
  6. COPYING / LICENSE : 저작권 및 사용권 정보
  7. BUGS : 알려진 오류 및 새로운 오류 보고 방법 안내

 

README 파일 형식으로 해당 프로젝트의 버전, 이전 버전과 변경된 사항들, 파일 목록 시스템 구조도 등을 작성하여 사용자들이 특이 사항들을 바로 확인 할 수 있도록 합니다.

 

README 작성법

README 작성은 사실 작성자 마음대로 작성해도 무방하나, 양식과 Markdown 문법에 맞게 작성할 경우 더욱 멋지고 읽기 쉽게 꾸밀 수 있습니다.

 

Markdown 소개

Markdown 은 일종의 마크업 언어로 텍스트에 태그를 이용해서 글자를 굵게 하거나 이미지를 삽입하거나 하는 행위가 가능합니다. Wikipedia 와 같은 Wiki 사이트에 글을 작성하는 경우 Wiki 언어를 이용해서 글을 작성하여야 하는데요, Markdown 언어는 그 Wiki 언어와 상당히 유사하게 볼 수 있습니다. 특히 Markdown 언어는 Wiki 문법에 비해 훨씬 더 간단하므로 익히는데 그리 긴 시간을 할애하지 않아도 작성이 쉽다는 장점을 가지고 있습니다.

요즈음 Markdown 의 사용이 보편화되고 있습니다. 블로그 플랫폼으로 유명한 WordPress 에서는 기본적으로 Markdown 을 지원하기 시작했고, Tumblr 나 Ghost 와 같은 블로그형 SNS 에서도 Markdown 언어를 기본적으로 지원하고 있습니다.

 

Markdown 의 장점

간결하고 읽기 쉽다.

Markdown 은 다른 Mark-up 언어에 비해 훨씬 알아보기 쉽습니다. 제목은 앞에 # 를 삽입해주면 되고, 글자를 강조하고 싶은 경우 글자 주위를 ** 을 이용하여 감싸주면 됩니다. HTML 로 글을 작성할 때에는 글이 실제로 브라우저에 어떻게 보여질지 미리 예상해보는 것이 꽤 어려웠다면 Markdown 으로 작성된 텍스트는 작성된 글이 브라우저에서 어떻게 보여질지 쉽게 예상해 볼 수 있습니다.

 

익히기 쉽다.

Markdown 은 상당히 간단합니다. John Gruber 가 처음에 Markdown 을 만들었을 때 일반적으로 많이 사용되는 서식들을 Markdown 으로 사용하고 복잡한 것은 HTML 로 편집하도록 디자인하였으므로 몇 가지 제한이 존재하기는 합니다만, Markdown 으로 글을 편집하는 경우 중간에 HTML 을 그대로 사용하여도 문제없습니다.

 

모바일 친화적이다.

요즈음 모바일을 통해 글을 작성하고 업로드하는 빈도가 상당히 많아졌습니다. 그런데, 모바일로 서식이 들어간 글을 작성할 때에는 상당한 불편함을 감수하여야 합니다. 특히 모바일에서는 텍스트 편집기 (Editor) 가 제대로 작동하지 않는 경우도 존재하고 정상적으로 작동하더라도 작은 화면으로 볼 수 있는 컨텐츠가 한정적이므로 에디터를 통해 글을 작성하는 것이 비효율적인 경우가 많습니다. 하지만 Markdown 을 이용하면 간단한 태그 만으로 서식을 손쉽게 삽입 가능하기 때문에 텍스트 에디터를 사용하는 것보다는 용이합니다.

 

텍스트 파일이므로 버전 관리 시스템 (Version Control) 을 이용하여 변경이력을 관리할 수 있으며 용량도 적어 보관이 효율적이다.

 

 

Markdown 의 단점

문법이 너무 단순하다

문법이 너무 단순하므로 해당 기능을 벗어나 HTML 을 사용하여야 하는 경우가 생길 수 밖에 없습니다. 예를 들어 Markdown 에는 이미지를 정렬하는 문법이 존재하지 않습니다. 따라서 이미지를 정렬하려면 HTML 의 img 태그를 사용하여야만 합니다. 또한 태그에 클래스 지정 등이 불가능하므로 클래스나 id 를 지정하려면 역시 HTML 을 사용하여야만 가능합니다.

 

확장 문법이 많다. (표준이 없다.)

이것은 앞에서 언급한 첫 번째 단점의 연장선이라고 볼 수 있습니다. 문법이 너무 간결하므로 해당 불편함을 해소하기 위하여 여러가지 확장 문법들이 생기기 시작했고, 그런 파편화 때문에 한 곳에서 잘 작동하는 Markdown 문서가 다른 곳에서는 제대로 작동하지 않는 문제가 발생하곤 합니다.

 

멀티미디어 삽입이 불편하다. (모든 HTML Mark-up 을 대신하지 못한다.)

텍스트 에디터에서 이미지를 삽입하는 경우, 일반적으로 이미지 업로드 버튼을 이용하여 이미지를 삽입합니다. 하지만 Markdown 은 그저 텍스트만 입력이 가능하기 때문에 이미지를 삽입하는 행위 뿐 아니라 이미지를 업로드 한 후 그 주소를 가져오는 과정들이 모두 분리되어 있습니다. 따라서 Markdown 을 이용하여 블로그의 글을 작성하는 경우에 가장 까다로운 절차가 이미지를 삽입할 때 입니다. 물론, YouTube 와 같은 사이트에 올려진 외부 동영상을 삽입하는 경우 텍스트 에디터를 사용하는 것과 큰 차이는 없습니다.

 

Markdown 사용법 (문법)

제목

# 을 하나 입력하면 HTML 의 <H1> 태그이고 # 을 두 개 입력하면 <H2> 태그를 의미합니다. # 은 총 6 개까지 사용이 가능하며 # 의 개수가 늘어날 때 마다 하위 단계의 제목으로 설정됩니다.

#제목
##부제목
### 소제목

 

번호가 없는 리스트

* 목록
* 목록 1
– 다른 목록
– 다른 목록 1
+ 다른 목록 3

 

번호가 있는 리스트
(반드시 숫자를 정렬하여 사용하실 필요는 없습니다.)

1 첫 번째
2 두 번째
3 세 번째
4 네 번째
5 다섯 번째

 

기울임 꼴

*텍스트*
OR
_텍스트_

 

굵은 글씨

**텍스트**
OR
__텍스트__

 

인용
(인용문 내부에 인용문을 부가적으로 삽입하시려면 > 을 추가하시면 됩니다.)

> 텍스트

 

인라인 링크

[텍스트](링크 주소)

 

참조 링크

[텍스트][참조명]
[참조명] : 링크 주소

 

이미지

![텍스트](이미지 링크 주소)

 

구분선 (수평선)
( _ , * , – 을 3 개 이상 씩 나열)

___
***
___

 

코드 블럭

앞에 공백 4 개 이상 삽입

 

도움이 되셨기를 바라며, 새해 복 많이 받으십시오.
고맙습니다.

Advertisements

One comment

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s