마크다운 문서 작성법 (+github 프로필 만들기)

우선, 이렇게 새로운 카테고리를 만들고 글을 작성하게 해주신 동기 Y님께 심심한 감사를..!😆

---

README.md가 뭘까?

github의 모든 repo에는 README.md 라는 파일을 작성할 수 있다.

README 파일은 github에서 특정 repo를 선택했을 때 가장 먼저 미리보기가 가능한 파일이며, 개인 프로필 작성이나 해당 repo를 설명하기 위해서 사용한다. 개인 프로필이라면 자신이 어떤 사람인지를 소개할 수 있는 도구가 될 것이고, 특정 프로젝트를 담는 repo라면 해당 프로젝트에 대한 사용설명서 같은 역할을 할 것이다.

잔디 키우려고 github에 올려둔 예전 학습자료의 README

README.md 라는 파일의 확장자명은 git에서만 사용하는 것인데, 마크다운 언어의 문법으로 작성했음을 의미한다. (일반 윈도우나 맥 운영체제에서는 메모장인 .txt 확장자를 사용한다고 한다.)

마크다운 문법이라니 생소하겠지만 알고보면 그리 어렵지 않다. (나는 사용해본 적이 없지만) 테크 블로그로 많이 사용되는 벨로그가 마크다운 언어 형식을 쓴다고 하고, 요즘 2030세대가 노트로 많이 사용하는 Notion도 마크다운 문법을 사용한다. 또한 협업툴인 슬랙(Slack)도 일부 마크다운 문법을 지원하고 있다.

💡 여기서 잠깐!
- 마크다운 언어(Markdown) : 간단한 서식 지정을 위한 경량 마크업 언어.
- 마크업 언어(Markup) : HTML처럼 문서의 구조를 표현하기 위한 언어.

---

마크다운 언어의 문법과 작성법

사실 나는 앞서 예시로 사용된 사진에도 적혀있듯이, 작년 연말에 내일배움카드로 코딩 입문 수업을 들으면서 마크다운 언어의 문법에 대해 아주 잠깐 배웠었다. 덕분에 github 프로필도 어렵지 않게 작성할 수 있었다.

우선 마크다운 문서는 VS code에서 README.md 라는 파일을 만들고, 우측 상단의 '측면에서 미리보기 열기(Open Preview to the Side)'를 클릭해서 미리보면서 작성할 수 있다. 지금 글을 쓰며 확인해보니 단축키도 있는데, 나는 저 버튼이 돋보기 모양이 있어 직관적이라 그냥 버튼 눌러서 사용하는 편이다.🙂

미리보기를 무사히 열었다면, 각 항목마다 마크다운 언어로 어떻게 작성하는지 알아보기 전에!

필자도 현재 배우는 중이라 아래에 서술하는 내용이 정확하지 않을 수 있고, 새롭게 알게 된게 있으면 본 글에 계속 업데이트하고 있으니, 만약 이 글을 참고하여 md파일을 작성한다면 미리보기로 확인해보고 commit하시길 추천한다!😉

---

제목

해시태그의 개수에 따라 글씨의 크기가 바뀌고, 해시태그가 많을수록 글자가 작아진다. html의 h1~6 태그에서 숫자가 클수록 글자가 작아지는 것과 같다. 1~2에만 밑줄이 그어지는건, 특정 파트의 제목으로 많이 쓰여서 그렇지 않을까 하는 개인적인 생각..🤔

주의할 부분은, 해시태그와 텍스트 사이에 반드시 띄어쓰기를 해야한다. 띄어쓰기 없으면 제목으로 인식이 안 된다.

---

목록

html 태그에 ordered list와 unordered list가 있듯이 여기도 마찬가지다. 플러스, 마이너스, 별을 입력하면 순서 없는 목록이 생성되고 키보드의 tab키를 누르면 한 칸 들여쓰기가 된다. 순서가 있는 목록은 위 예시처럼 숫자를 입력하고 Enter 치면 자동으로 생성된다.

---

링크와 이미지 (+비디오)

• 링크는 사용자가 클릭할 수 있는 텍스트를 대괄호 사이에 입력하고, 뒤에 소괄호로 링크를 적는다. html의 a 태그 속성 href에 링크 주소를 적고, 여는 태그와 닫는 태그 사이에 클릭할 수 있는 텍스트를 적는 것과 같다.
• 이미지도 링크와 작성 방식이 같은데, 앞에 느낌표를 추가해야한다. 대괄호 안에는 사진을 설명할 수 있는 텍스트를 작성하고, 소괄호에 이미지의 링크를 넣는다. html의 img 태그 속성 src에 링크를 넣고 alt에 설명을 넣는 것과 같다.
  → 특정 프로젝트를 소개하는 github repo의 README.md에 이미지를 입력하려면, 해당 repo에 이미지가 업로드되어 있어야 한다. repo에 올려둔 이미지 링크를 사용해야 github에서 README가 미리보기 됐을 때 정상 출력된다는 얘기!
  → mp4 등의 확장자를 갖는 비디오 파일의 경우, README.md에 그대로 올릴 수 없어서 gif로 변환하여 이미지 첨부하는 방식으로 올려야 한다.
• github 프로필에서 뱃지를 클릭했을 때 특정 링크로 이동하는 기능을 넣고 싶다면, 아래 예시처럼 사진을 입력한 부분을 모두 대괄호로 감싸서 링크의 형식으로 작성하면 된다.

---

구분선

구분선은 띄어쓰기 상관없이 마이너스나 별을 3개 이상만 입력하면 되는데, 이렇게 입력하면 굵은 구분선이 생긴다.

얇은 구분선을 만들려면 해시태그(#) 하나만 입력하면 된다.

---

문자 꾸미기

마크다운 문법으로 볼드체, 이탤릭체를 작성하려면 별표 혹은 언더바를 사용하면 된다. 위 예시에서 볼 수 있듯, 이탤릭체는 기호 1개, 볼드는 기호 2개, 볼드와 이탤릭을 같이 적용하려면 기호 3개를 텍스트 양 옆에 띄어쓰기 없이 입력한다. 띄어쓰기가 있으면 제대로 인식이 안 되므로 주의할 것!😉

참고로 위 예시에서도 볼 수 있지만, 줄바꿈은 Enter를 두 번 쳐야한다.

---

인용구

>를 사용하여 인용구 표현이 가능하다. 예시에서 볼 수 있듯, 기호의 개수가 많아질수록 '하위 요소'가 된다.

---

인라인 코드, 블록 코드

• 인라인 코드는 강조하고 싶은 부분의 양 끝에 '백틱(backtick)'을 하나씩 추가하면 된다. backtick은 키보드의 tab키 위쪽에 물결과 함께 위치한 기호이다. 개인적으로 backtick은 노션에서 프로그램의 단축키 정리할 때 유용한 기능이었다.👍
• 블록 코드는 작성하는 코드를 블록으로 보여주고 싶을 때 사용하는건데, backtick을 양 끝에 3개씩 입력하면 된다. 개인적인 생각으로는 처음에 3개 입력해서 블록 코드를 열고, 언어의 종류와 코드를 작성하고 다시 3개를 입력해서 닫아주는 것 같다.

※ 일부 내용 참고 
https://velog.io/@gmlstjq123/Readme.md-%ED%8C%8C%EC%9D%BC-%EC%9E%91%EC%84%B1%EB%B2%95

---

그리고 잠깐 개인적인 얘기.
이번에 SeSAC으로 프론트엔드를 공부하게 되면서, github에 내가 작년 연말에 내일배움카드로 공부한 내용들을 전부 올리면 개인 포트폴리오도 될 수 있고, '잔디'(contributions)도 늘릴 수 있을 것 같아서 지난주에 업로드를 했다. 이걸 github로 push하고 어떤 내용인지 README 파일을 적어둬야 할 것 같아서 찾아보다가, 요즘 개발자들은 github 프로필을 굉장히 화려하게 꾸민다는 사실을 알게 되었다!🙄 뱃지가 여럿 달려있고 일목요연하게 정리된 프로필들을 보니까 나도 하고 싶어져서 폭풍 구글링으로 찾아서 조금씩 작성하고 있었는데, 마침 슬랙에 github 프로필 만드는 방법이 공유되어서 나도 내가 참고했던 링크들을 공유했더니, 동기님께 마크다운 문법에 대한 질문이 들어왔던게 생각나서 연휴동안 이 글을 쓰게 됐다.😁

---

GitHub 프로필 만들기

일단 가장 먼저 해야하는건, 자신의 github 아이디와 똑같은 이름의 repo를 만드는 것.

그 다음으로 README.md 파일을 하나씩 꾸며나가면 된다.

필자가 적용한건 → Header, 방문자수 뱃지, 기술 뱃지, github stats, Top langs, SNS 뱃지, 블로그 최신글 위젯이다.

---

1. header

사실 이건 필자가 만든 초기 README 파일에는 없었던건데 다른 블로그에서 header 넣은걸 보고 멋지길래, 아래 주소에서 디자인 확인하고 마음에 드는 걸로 추가해서 컬러에 커스터마이징을 했다.

https://github.com/kyechan99/capsule-render

GitHub - kyechan99/capsule-render: 🌈 Dynamic Coloful Image Render

---

2. 방문자수 뱃지

아래 사이트에서 만들 수 있는데, 컬러를 개인이 원하는대로 바꿀 수 있어서 전체적인 디자인에 맞게 수정했다.

https://hits.seeyoufarm.com/

HITS

---

3. 기술 뱃지

기술 관련 뱃지들은 아래 사이트를 통해서 만들 수 있다.

https://shields.io/

Shields.io | Shields.io

뱃지를 직접 만들려면 아래 주소에서 뱃지이름, 뱃지배경색, 뱃지스타일, 로고, 로고컬러를 커스텀하면 된다.

https://img.shields.io/badge/{배지이름}-{뱃지배경색}?style={스타일}&logo={로고}&logoColor={로고컬러}

https://velog.io/@shlee327/shield.io-%EB%A7%88%ED%81%AC%EB%8B%A4%EC%9A%B4-%EB%B0%B0%EC%A7%80-%EB%A7%8C%EB%93%A4%EA%B8%B0

[Shield.io] 마크다운 배지 만들기

• 뱃지이름: 뱃지에 보여질 이름을 작성한다.
• 뱃지배경색: 아래 Simple Icons 사이트에서 기업 이름을 검색해서 해시태그를 제외한 Hex Code를 붙여넣는다.
• 로고: Simple Icons 사이트에 나오는 기업의 공식명칭으로 작성해야 정상 출력된다.
• 로코컬러: 블랙, 화이트 중에 뱃지의 배경색이랑 어울리는 것으로 설정.
• 뱃지 디자인: 5종류가 있는데 아래 사진과 같다.

프로필 처음 만들어보는 사람이 뱃지를 직접 만드는건 어려우니까, 테크 블로거들이 공유한 코드를 가져다쓰는 것도 편리하다..😅 참고로 뱃지 제작할 때 기업별 컬러가 궁금하다면, 아래 사이트에서 기업명을 검색하면 hex code가 나오니까 복사해서 사용하면 된다.

https://simpleicons.org/

Simple Icons

---

4. GitHub stats, Top langs 위젯

많은 분들이 프로필에 걸어뒀던 깃허브 스탯과 Top langs 위젯.

아래 repo의 README에 매우 친절한 한국어 설명도 있으니 참고해서 만들면 된다.

테마가 매우 다양한데, 그 중에 마음에 드는 걸로 위젯 2종의 디자인을 맞췄다.

https://github.com/anuraghazra/github-readme-stats

GitHub - anuraghazra/github-readme-stats: :zap: Dynamically generated stats for your github readmes

.
→ 레이아웃-컴팩트 하면 그래프 하나에 여러 종류 언어가 다 나옴

---

5. 블로그 최신글 위젯

이것도 초기 README 파일에는 없었던 내용인데, 프로필을 만들다가 다른 블로그에서 티스토리 최신글 위젯을 github 프로필에 달 수 있다는걸 알게 되어 추가했다. 테마가 다양하지만 기본이 제일 깔끔한 것 같아서 그냥 default로 두었다.

(2024년 3월부터 위젯이 제대로 보이지 않아서 삭제함..)

https://github.com/loosie/github-readme-tistory-card

GitHub - loosie/github-readme-tistory-card: github profile readme에 tistory 카드를 올려보자

---

그렇게 일부 수정하고 업로드한 내 github 프로필은 아래 주소에서 확인할 수 있다!👀

https://github.com/hjinn0813

hjinn0813 - Overview

2024년 7월에 프로필 업그레이드한 기록은 여기 있어요 👉 https://hjinn0813.tistory.com/93

GitHub 프로필 업그레이드 하기