마크다운(Markdown) 기본 문법 살펴보기

April 17, 2025

마크다운이란?

본격적인 문법 설명에 앞서, 마크다운이 무엇인지 가볍게 살펴보겠습니다.

과거에는 웹 페이지에 글을 쓰기 위해 HTML 이나 XML 같은 태그로 텍스트를 일일이 감싸야 했습니다.
예를 들어 글씨를 굵게 만들려면 <b>내용</b>처럼 작성해야 했습니다.
이렇게 태그를 통해 문서의 구조를 정의하는 방식을 마크업(Markup) 언어라고 합니다.

하지만 마크업 언어는 작성이 복잡하고 글의 내용 자체에 집중하기 어렵다는 단점이 있었습니다.
이를 해결하고자 2004년 존 그루버(John Gruber)는 복잡함을 덜어낸 마크다운(Markdown) 을 만들었습니다.
이름에서 알 수 있듯이, 마크업의 번거로움을 '다운(Down)' 시키고 "읽기 쉽고 쓰기 쉬운 텍스트 형식으로 글을 쓰자"는 철학을 담고 있습니다.

초기의 마크다운은 자유도가 높았던 만큼 해석 방식이 다양해 문법의 파편화가 일어났습니다.
이를 바로잡기 위해 2014년 엄격한 표준 규격인 CommonMark가 발표되었고, 여기에 실무에 필요한 기능을 더해 현재 가장 널리 쓰이고 있는 것이 바로 GitHub Flavored Markdown(GFM) 입니다.
GFM 은 표준 문법에 표(Table), 취소선(Strikethrough), 작업 목록(Task Lists) 등 실용적인 기능을 추가하여 개발자뿐만 아니라 많은 글쓰기 플랫폼에서 채택하고 있습니다.

그래서 이 글에서도 가장 범용적인 GFM 문법을 기준으로 사용법과 결과물을 함께 살펴보겠습니다.

Markdown 기본 문법

블록 요소 (Leaf Blocks & Container Blocks)와 라인 요소 (Inlines) 를 구분하여 알아봅니다.

블록 요소 (Leaf Blocks & Container Blocks)

1.1 테마 구분선 (Thematic Breaks)

섹션을 시각적으로 분리할 때 사용합니다.

*** 또는 --- 또는 ___

***

---

___

1.2 ATX 헤딩 (ATX Headings)

기호를 사용하여 1단계부터 6단계까지의 제목을 만듭니다.

작성법:

# 제목 1
## 제목 2
### 제목 3
#### 제목 4
##### 제목 5
###### 제목 6

제목 1

제목 2

제목 3

제목 4

제목 5

제목 6

또한, 텍스트 아래에 등호(===)나 하이픈(---)을 여러 개 추가하여 1단계 및 2단계 제목을 만들 수도 있습니다. (Setext 방식)

작성법:

제목 1
===

제목 2
---

1.3 코드 블록 (Code Blocks)

백틱(```) 3개 또는 물결(~~~) 3개 이상으로 감싸며, 언어 이름을 명시하여 하이라이팅이 가능합니다.

```javascript
console.log("Hello GFM");
``` 

또는

~~~javascript
console.log("Hello GFM");
~~~

console.log("Hello GFM");

1.4 인용문 (Block Quotes)

줄 처음에 > 기호를 붙입니다. 중첩해서 사용할 수도 있습니다.

> 인용구 내용입니다.

인용구 내용입니다.

1.5 목록 (Lists)

순서 없는 목록: -, +, * 중 하나를 사용합니다.
순서 있는 목록: 숫자를 사용합니다.

1. 첫 번째 
2. 두 번째
- 순서 없음
+ 순서 없음
* 순서 없음

첫 번째
두 번째

순서 없음

순서 없음

순서 없음

또한, 목록은 들여쓰기를 통해 중첩 구조를 만들 수 있습니다.

1. 첫 번째 항목
    - 하위 목록 1
    - 하위 목록 2
2. 두 번째 항목
    1. 하위 순서 목록 1

첫 번째 항목
- 하위 목록 1
- 하위 목록 2
두 번째 항목
1. 하위 순서 목록 1

1.6 표 (Tables - GFM 확장)

파이프(|)와 하이픈(-)으로 열과 행을 구분합니다. 하이픈 줄에 콜론(:)을 넣어 정렬을 지정합니다.

작성법:

| foo | bar |
| --- | --- |
| baz | bim |

foo	bar
baz	bim

1.7 작업 목록 (Task List Items - GFM 확장)

목록 기호 뒤에 대괄호를 붙여 체크박스를 만듭니다.

작성법:

[ ] 미완료, 
[x] 완료

미완료
완료

2. 인라인 요소 (Inlines)

텍스트 내부에서 특정 단어나 문장에 서식을 지정할 때 사용합니다.

2.1 강조 및 강한 강조 (Emphasis)

기울임: *텍스트* 또는 _텍스트_

굵게: **텍스트** 또는 __텍스트__

텍스트 또는 텍스트
텍스트 또는 텍스트

2.2 코드 스팬 (Code Spans)

문장 중간에 코드를 표시할 때 백틱(`) 하나로 감쌉니다.

`inline code` 입니다.

inline code 입니다.

2.3 취소선 (Strikethrough - GFM 확장)

텍스트를 물결표 두 개로 감쌉니다.

~~취소할 내용~~

~~취소할 내용~~

2.4 링크 및 이미지 (Links & Images)

링크: [깃주소]([URL](https://github.com/SongWoody)) 입니다.

이미지: ![마크다운](https://upload.wikimedia.org/wikipedia/commons/4/48/Markdown-mark.svg)

깃주소 입니다.

마크다운

2.5 자동 링크 (Autolinks & GFM 확장)

기본: <https://google.com> 처럼 괄호로 감싸면 링크가 됩니다.

GFM 확장: www.google.com처럼 주소만 적어도 자동으로 링크로 변환됩니다.

https://google.com

www.google.com

2.6 이스케이프 (Backslash Escapes)

마크다운 기호를 문자로 그대로 출력하고 싶을 때 앞에 \를 붙입니다.

\# 이 기호는 제목이 아닙니다.
\`code block\` 이 기호는 코드 블록이 아닙니다.

# 이 기호는 제목이 아닙니다.

`code block` 이 기호는 코드 블록이 아닙니다.

2.7 줄 바꿈 (Line Breaks)

Hard Break: 문장 끝에 공백 2개를 넣거나 백슬래시(\)를 넣고 엔터를 칩니다.

Soft Break: 그냥 엔터를 한 번 치면 문서상에서는 이어져 보이지만 소스 코드상에서는 줄이 바뀝니다.\

    안녕하세요.\
    반가워요. 
    이렇게 바로 아래에 쓰면 이어져서 나옵니다.

안녕하세요.
반가워요. 이렇게 바로 아래에 쓰면 이어져서 나옵니다.

2.8 HTML 직접 사용 (Raw HTML)

마크다운의 장점 중 하나는 HTML과 완벽하게 호환된다는 점입니다. 마크다운 문법으로 표현하기 힘든 복잡한 스타일이나 구조가 필요할 때, 문서 안에 HTML 태그를 직접 작성할 수 있습니다.

작성법:

<p style="color:red;">이 텍스트는 빨간색입니다.</p>

<table>
    <tr>
        <td>HTML 표도</td>
        <td>사용 가능합니다.</td>
    </tr>
</table>

이 텍스트는 빨간색입니다.

HTML 표도

사용 가능합니다.

번외

밑줄은 어떻게 칠까?

안타깝게도 Markdown 에서는 밑줄을 지원하지 않습니다.
하여 밑줄을 사용하기 위해서는 html 의 <u> 태그를 사용해야합니다.

    <u>밑줄</u>을 치고 싶습니다.

밑줄을 치고 싶습니다.

마무리

Markdown은 간단하면서도 강력한 문법을 제공하여 문서를 더욱 쉽게 작성할 수 있도록 도와줍니다.
GitHub의 README 파일뿐만 아니라, 블로그, 기술 문서, 협업 문서 등 다양한 곳에서 활용할 수 있으니,
자주 사용하면서 익숙해지면 여러 곳에서 유용하게 사용할 수 있습니다. 😀

참고

GitHub Flavored Markdown Spec