마크다운 작성법 완벽 가이드: 개발자 필수 문서 도구

마크다운이란?

마크다운(Markdown)은 텍스트 기반의 경량 마크업 언어입니다. 2004년 존 그루버(John Gruber)가 개발했으며, 간단한 문법으로 서식이 있는 문서를 작성할 수 있습니다. 일반 텍스트로 작성하지만 렌더링하면 제목, 굵은 글씨, 목록, 링크, 이미지, 코드 블록 등이 깔끔하게 표시됩니다.

마크다운은 개발자 세계에서 사실상 표준 문서 형식입니다. GitHub의 README 파일, 기술 문서, 블로그 글, 위키, 노션, 슬랙 메시지 등 수많은 곳에서 마크다운을 사용합니다. 한 번 배우면 다양한 환경에서 활용할 수 있어 투자 대비 효과가 매우 큰 기술입니다.

마크다운을 배워야 하는 이유

• 빠른 문서 작성: 마우스 없이 키보드만으로 서식을 적용할 수 있어 문서 작성 속도가 빨라집니다.
• 플랫폼 독립적: 마크다운 파일은 어떤 텍스트 에디터에서도 열 수 있습니다. 특정 소프트웨어에 종속되지 않습니다.
• 버전 관리: 텍스트 파일이므로 Git으로 변경 이력을 추적할 수 있습니다. Word 파일은 Git으로 관리하기 어렵습니다.
• 변환 용이: HTML, PDF, Word 등 다양한 형식으로 변환할 수 있습니다.
• 어디서나 사용: GitHub, GitLab, Notion, Slack, Discord, Reddit, 블로그 플랫폼 등 수많은 서비스가 마크다운을 지원합니다.

기본 문법: 제목

제목은 # 기호로 표시합니다. #의 개수에 따라 제목의 레벨이 달라집니다.

• # 제목 1: 가장 큰 제목 (HTML의 h1)
• ## 제목 2: 두 번째 레벨 제목 (h2)
• ### 제목 3: 세 번째 레벨 제목 (h3)
• #### 제목 4: 네 번째 레벨 (h4)

# 뒤에 반드시 공백을 하나 넣어야 합니다. "#제목"은 인식되지 않고 "# 제목"이 올바른 형식입니다. 일반적으로 문서에서 h1은 하나만 사용하고, 본문의 섹션 구분에는 h2와 h3를 사용합니다.

기본 문법: 텍스트 서식

• 굵은 글씨: **텍스트** 또는 __텍스트__
• 기울임: *텍스트* 또는 _텍스트_
• 굵은 기울임: ***텍스트***
• 취소선: ~~텍스트~~
• 인라인 코드: `코드` (백틱으로 감싸기)

가장 많이 사용하는 것은 **굵은 글씨**와 `인라인 코드`입니다. 기술 문서에서 변수명, 함수명, 명령어 등을 표시할 때 인라인 코드를 사용합니다.

기본 문법: 목록

순서 없는 목록

-, *, + 기호 중 하나를 사용합니다. 들여쓰기로 하위 항목을 만들 수 있습니다.

• - 첫 번째 항목
• - 두 번째 항목
•   - 하위 항목
•   - 하위 항목 2

순서 있는 목록

숫자와 마침표를 사용합니다. 실제 렌더링 시 자동으로 번호가 매겨지므로, 모든 항목에 1.을 사용해도 됩니다.

• 1. 첫 번째
• 2. 두 번째
• 3. 세 번째

체크리스트

할 일 목록을 만들 수 있습니다. GitHub에서 특히 유용합니다.

• - [x] 완료된 항목
• - [ ] 미완료 항목

기본 문법: 링크와 이미지

링크

대괄호에 텍스트, 소괄호에 URL을 넣습니다.

[표시 텍스트](URL)

예시: [Google](https://google.com) → Google이라는 링크가 생성됩니다.

이미지

링크 앞에 느낌표(!)를 추가합니다.


대체 텍스트(alt text)는 이미지가 표시되지 않을 때 보이는 텍스트이며, 접근성을 위해 반드시 작성하는 것이 좋습니다.

기본 문법: 코드

인라인 코드

백틱(`)으로 감싸면 인라인 코드가 됩니다. 문장 중간에 `console.log()`처럼 코드를 표시할 때 사용합니다.

코드 블록

백틱 세 개(```)로 감싸면 코드 블록이 됩니다. 첫 번째 줄의 ``` 뒤에 언어 이름을 적으면 구문 강조(Syntax Highlighting)가 적용됩니다.

예시: ```python 으로 시작하면 Python 문법에 맞게 코드가 색상으로 구분되어 표시됩니다. javascript, html, css, java, bash 등 다양한 언어를 지정할 수 있습니다.

기본 문법: 인용과 구분선

인용문

> 기호로 인용문을 만듭니다. 다른 문서나 발언을 인용할 때 사용합니다.

> 이것은 인용문입니다.

>> 를 사용하면 중첩 인용도 가능합니다.

구분선

--- 또는 *** 를 사용하면 수평 구분선이 생성됩니다. 섹션을 시각적으로 분리할 때 유용합니다.

고급 문법: 테이블

파이프(|)와 하이픈(-)으로 테이블을 만들 수 있습니다.

| 항목 | 설명 | 가격 |

|------|------|------|

| 사과 | 빨간 과일 | 1000원 |

| 바나나 | 노란 과일 | 2000원 |

콜론(:)을 사용하여 정렬을 지정할 수 있습니다. :--- (왼쪽), :---: (가운데), ---: (오른쪽) 정렬입니다.

마크다운 에디터 추천

데스크탑 에디터

• Visual Studio Code: 가장 인기 있는 코드 에디터. 마크다운 미리보기 기능 내장, 확장 프로그램으로 기능 확장 가능. 무료.
• Typora: 실시간 렌더링을 지원하는 마크다운 전용 에디터. 작성하면서 바로 결과를 확인할 수 있어 매우 직관적. 유료.
• Obsidian: 마크다운 기반 노트 앱. 문서 간 링크, 그래프 뷰 등 지식 관리에 특화. 개인 사용 무료.

온라인 에디터

• HackMD / CodiMD: 실시간 협업 가능한 온라인 마크다운 에디터.
• StackEdit: 브라우저에서 바로 사용할 수 있는 온라인 에디터.
• GitHub: 저장소의 파일을 웹에서 직접 편집 가능.

실전 활용: GitHub README 작성

GitHub에서 가장 먼저 접하는 마크다운은 README.md 파일입니다. 프로젝트의 소개, 설치 방법, 사용법 등을 설명하는 문서로, 잘 작성된 README는 프로젝트의 첫인상을 결정합니다.

좋은 README의 구성

• 프로젝트 제목과 설명: 한 줄로 프로젝트가 무엇인지 설명
• 설치 방법: 코드 블록으로 설치 명령어 제시
• 사용법: 기본 사용 예시와 스크린샷
• 기능 목록: 체크리스트나 목록으로 주요 기능 나열
• 기여 방법: 오픈소스 프로젝트의 경우 기여 가이드
• 라이선스: 프로젝트의 라이선스 정보

마크다운 학습 팁

• 자주 사용하기: 일상적인 메모나 노트를 마크다운으로 작성해보세요.
• 치트시트 활용: 처음에는 마크다운 치트시트를 옆에 두고 참고하세요. 일주일이면 기본 문법을 자연스럽게 익힐 수 있습니다.
• 미리보기 확인: VS Code의 미리보기(Ctrl+Shift+V)를 활용하여 결과를 확인하며 작성하세요.
• 다양한 플랫폼에서 연습: GitHub, Notion, 블로그 등에서 마크다운을 사용해보면 각 플랫폼의 미묘한 차이도 알 수 있습니다.

마크다운은 배우기 쉽고 활용도가 높은 도구입니다. 기본 문법 10여 가지만 익히면 대부분의 문서를 작성할 수 있으며, 개발자뿐 아니라 기획자, 디자이너, 학생 등 문서 작업이 많은 모든 사람에게 추천합니다.