Markdown이란 무엇인가?
개발자라면 GitHub에서 수도 없이 봐온 README.md 파일, 노션(Notion)에서 작성하는 문서, 블로그 포스트 — 이 모든 것의 공통점은 바로 Markdown(마크다운)으로 작성된다는 점입니다.
Markdown은 2004년 존 그루버(John Gruber)와 아론 스워츠(Aaron Swartz)가 만든 경량 마크업 언어입니다. 핵심 철학은 단순합니다: "읽기 쉬운 텍스트로 쓰면, 자동으로 예쁜 HTML이 된다." 복잡한 HTML 태그 없이도 제목, 굵은 글씨, 목록, 코드 블록 등을 손쉽게 표현할 수 있습니다.
오늘날 Markdown은 GitHub, GitLab, Notion, Obsidian, Discord, Reddit, Stack Overflow 등 수백 개의 플랫폼에서 사용되며, 기술 문서 작성의 사실상 표준(de facto standard)이 되었습니다.
Markdown 기본 문법 완전 정복
Markdown을 배우는 데는 30분도 걸리지 않습니다. 핵심 문법 10가지만 알면 90%의 문서를 작성할 수 있습니다.
1. 제목 (Headings)
# 기호의 개수로 제목의 수준을 표현합니다.
# H1 - 가장 큰 제목
## H2 - 섹션 제목
### H3 - 소섹션 제목
#### H4 - 세부 항목
HTML의 <h1> ~ <h4>에 각각 대응합니다. 문서의 계층 구조를 논리적으로 잡는 데 매우 중요합니다.
2. 텍스트 강조
**굵은 글씨** 또는 __굵은 글씨__
*기울임체* 또는 _기울임체_
~~취소선~~
**_굵고 기울인_** 텍스트
결과: 굵은 글씨, 기울임체, 취소선, 굵고 기울인 텍스트
3. 목록 (Lists)
순서 없는 목록은 -, *, +로 시작합니다:
- 사과
- 바나나
- 제주 바나나 (들여쓰기로 중첩 가능)
- 수입 바나나
- 체리
순서 있는 목록은 숫자 + 점으로 작성합니다:
1. 첫 번째 단계
2. 두 번째 단계
3. 세 번째 단계
실제 번호가 틀려도 Markdown이 자동으로 순서를 맞춰줍니다. 1. 1. 1.으로 써도 1, 2, 3으로 렌더링됩니다.
4. 링크와 이미지
[링크 텍스트](https://hmapps.kr)
[링크 텍스트](https://hmapps.kr "마우스 오버 시 툴팁")
링크와 이미지의 문법이 비슷한 것을 눈치채셨나요? 이미지는 앞에 !만 붙이면 됩니다. 직관적이고 기억하기 쉬운 설계입니다.
5. 코드 표현
인라인 코드는 백틱 1개로 감쌉니다:
변수 `userName`에 값을 할당합니다.
코드 블록은 백틱 3개로 감싸고, 언어를 명시하면 문법 강조(syntax highlighting)가 적용됩니다:
```javascript
function greet(name) {
return `안녕하세요, ${name}!`;
}
console.log(greet('HMApps'));
```
지원하는 언어: javascript, python, java, typescript, bash, sql, html, css, json, yaml 등 수십 가지.
6. 인용문 (Blockquote)
> 이것이 인용문입니다.
>
> 여러 줄로 작성할 수 있으며,
>> 중첩 인용도 가능합니다.
API 문서에서 주의사항을 강조하거나, 원문을 인용할 때 유용합니다.
7. 구분선 (Horizontal Rule)
---
***
___
세 가지 방법 모두 <hr>로 렌더링됩니다. 섹션을 시각적으로 구분할 때 사용합니다.
8. 표 (Table)
| 이름 | 역할 | 경험 |
|------|------|------|
| 김철수 | 백엔드 | 5년 |
| 이영희 | 프론트엔드 | 3년 |
| 박민준 | DevOps | 7년 |
표 정렬 방법:
| 왼쪽 정렬 | 가운데 정렬 | 오른쪽 정렬 |
|:----------|:-----------:|-----------:|
| 텍스트 | 텍스트 | 텍스트 |
9. 체크박스 (Task List)
GitHub Flavored Markdown(GFM)에서 지원하는 체크박스입니다:
- [x] 요구사항 분석 완료
- [x] 디자인 시안 확정
- [ ] 백엔드 API 개발
- [ ] 프론트엔드 연동
- [ ] QA 테스트
이슈 트래커나 PR 설명에서 진행 상황을 보여줄 때 매우 유용합니다.
10. 이스케이프 문자
Markdown 문법 기호를 그대로 표시하려면 백슬래시(\)로 이스케이프합니다:
\*별표를 그대로 표시\*
\# 해시를 그대로 표시
\[대괄호\]
Markdown 실전 활용 사례
GitHub README.md 작성
GitHub 프로젝트의 첫인상을 결정하는 README.md는 Markdown의 가장 중요한 활용 사례입니다. 잘 작성된 README는 오픈소스 프로젝트의 채택률을 크게 높입니다.
효과적인 README 구조:
- 프로젝트 이름 + 뱃지(Badge): CI 상태, 버전, 라이선스
- 한 줄 설명: 프로젝트가 무엇을 하는지 명확하게
- 스크린샷 또는 데모 GIF: 시각적 임팩트
- 설치 방법: 코드 블록으로 복사 가능하게
- 사용법: 가장 흔한 사용 사례부터
- 기여 방법: 어떻게 참여할 수 있는지
- 라이선스: MIT, Apache 등
# 🚀 MyProject
[](...)
[](...)
> 한 줄로 프로젝트를 설명합니다.
## 설치
```bash
npm install myproject
```
## 빠른 시작
```javascript
import { MyProject } from 'myproject'
const app = new MyProject({ option: true })
```
기술 블로그 포스팅
Gatsby, Hugo, Jekyll, Next.js 등 대부분의 정적 사이트 생성기(SSG)는 Markdown을 기본 콘텐츠 형식으로 지원합니다. 프론트매터(Frontmatter)를 활용하면 메타데이터까지 함께 관리할 수 있습니다.