# 마크다운 작성법 — 기본부터 심화까지

생성형 AI(LLM)와 일할 때 마크다운은 가장 기본이 되는 글쓰기 형식입니다. 클로드에게 문서를 주고받을 때도, 옵시디언에 기록을 남길 때도, 깃허브에 올릴 때도 같은 문법을 씁니다. 부호 몇 개만 익히면 제목·목록·표·강조를 자유롭게 쓸 수 있습니다.

이 문서는 **기본 → 확장 → 심화** 순서로 정리했습니다. 처음이라면 1장만 읽어도 문서 작성에는 충분하고, 2장은 표·콜아웃·수식이 필요할 때, 3장은 옵시디언을 본격적으로 쓸 때 펼쳐 보시면 됩니다. 급할 때는 맨 뒤 **부록 — 빨리 찾아보기**만 봐도 됩니다.

> 유소장.ai 「생성형 AI(LLM), 하루 만에 일에 쓰는 법」 1일 집중 특강 배포 자료

---

## 1장. 기본 문법

이 장만 알아도 대부분의 문서를 쓸 수 있습니다.

### 제목

`#` 기호의 개수로 수준을 정합니다. 기호 뒤에 공백 한 칸을 꼭 넣습니다.

```markdown
# 1수준 제목
## 2수준 제목
### 3수준 제목
#### 4수준 제목
##### 5수준 제목
###### 6수준 제목
```

실무 문서에서는 3수준까지만 써도 충분합니다.

### 텍스트 강조

```markdown
**굵은 텍스트**        별표 두 개
*기울임 텍스트*        별표 하나
***굵은 기울임***      별표 세 개
~~취소선~~             물결표 두 개
==하이라이트==         등호 두 개 (옵시디언 지원)
```

각각 **굵게**, *기울임*, ***굵은 기울임***, ~~취소선~~으로 표시됩니다.

### 목록

순서 없는 목록은 하이픈으로 씁니다.

```markdown
- 첫 번째 항목
- 두 번째 항목
	- 들여쓴 항목 (탭 또는 공백 두 칸)
- 세 번째 항목
```

순서 있는 목록은 숫자와 마침표를 씁니다.

```markdown
1. 첫 번째 단계
2. 두 번째 단계
	1. 하위 단계 A
	2. 하위 단계 B
```

체크리스트는 대괄호 안의 공백과 `x`로 구분합니다.

```markdown
- [x] 완료된 할 일
- [ ] 아직 안 한 할 일
```

- [x] 완료된 할 일
- [ ] 아직 안 한 할 일

### 링크와 이미지

```markdown
[보일 글자](https://www.google.com)
![이미지 설명](이미지주소.png)
```

이미지는 링크 앞에 느낌표를 붙인 형태입니다. 대괄호 안의 설명은 이미지가 보이지 않을 때 대신 표시됩니다.

### 인용문

```markdown
> 이것은 인용문입니다.
> 여러 줄에 걸쳐 쓸 수 있습니다.

> 중첩도 가능합니다.
> > 한 단계 더 들여쓴 인용문
```

> 이것은 인용문입니다.
> 여러 줄에 걸쳐 쓸 수 있습니다.

### 코드

문장 안에서는 백틱 하나로 감쌉니다 — `이렇게`.

여러 줄은 백틱 세 개로 위아래를 감싸고, 첫 줄에 언어 이름을 적으면 색이 입혀집니다.

```python
def hello():
    print("Hello, Markdown!")
```

```javascript
const greet = () => console.log("Hello!");
```

### 수평선

하이픈 세 개 이상을 한 줄에 씁니다. 위아래로 빈 줄을 두세요.

```markdown
---
```

### 줄바꿈과 단락

빈 줄 하나를 두면 새 단락이 됩니다. 단락을 바꾸지 않고 줄만 바꾸려면 **줄 끝에 공백 두 칸**을 넣습니다.

---

## 2장. 확장 문법

기본을 넘어 실무에서 자주 쓰는 문법입니다. 표와 콜아웃은 특히 활용도가 높습니다.

### 표

```markdown
| 이름 | 역할 | 경력 |
|------|:----:|-----:|
| 김철수 | 프론트엔드 | 3년 |
| 이영희 | 백엔드 | 5년 |
```

| 이름 | 역할 | 경력 |
|------|:----:|-----:|
| 김철수 | 프론트엔드 | 3년 |
| 이영희 | 백엔드 | 5년 |

두 번째 줄의 콜론 위치로 정렬을 정합니다.

- `:---` 왼쪽 정렬
- `:---:` 가운데 정렬
- `---:` 오른쪽 정렬

### 각주

```markdown
마크다운은 John Gruber가 만들었습니다[^1].

[^1]: 각주는 문서 아무 곳에 적어도 맨 아래에 모입니다.
```

### 콜아웃 (옵시디언)

인용문 첫 줄에 `[!종류]`를 넣으면 색깔 있는 상자가 됩니다.

```markdown
> [!note] 참고사항
> 중요한 정보를 강조할 때 씁니다.

> [!tip] 팁
> 유용한 요령을 공유할 때.

> [!warning] 경고
> 무시하면 안 되는 내용.

> [!danger] 위험
> 치명적인 오류가 날 수 있을 때.
```

`[!info]+`처럼 더하기를 붙이면 펼친 상태로, `[!info]-`처럼 빼기를 붙이면 접힌 상태로 시작합니다.

### 수식 (LaTeX)

문장 안에서는 달러 기호 하나로 감쌉니다 — 원의 넓이는 $A = \pi r^2$ 입니다.

따로 떼어 크게 보이려면 달러 두 개로 위아래를 감쌉니다.

```markdown
$$
E = mc^2
$$

$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$
```

### 다이어그램 (Mermaid)

코드 블록의 언어 자리에 `mermaid`를 적으면 글로 쓴 대로 그림이 그려집니다.

```mermaid
graph TD
    A[시작] --> B{조건 분기}
    B -->|Yes| C[작업 수행]
    B -->|No| D[종료]
    C --> D
```

주고받는 순서를 그리는 시퀀스 다이어그램도 자주 씁니다.

```mermaid
sequenceDiagram
    사용자->>서버: 요청
    서버->>DB: 쿼리
    DB-->>서버: 결과
    서버-->>사용자: 응답
```

### 옵시디언 내부 링크

```markdown
[[노트 이름]]                다른 노트로 연결
[[노트 이름#제목]]            특정 제목으로 연결
[[노트 이름|표시할 텍스트]]     다르게 보이게 하기

![[노트 이름]]               노트 전체를 끼워 넣기
![[image.png]]              이미지 넣기
![[image.png|300]]          너비 300으로 넣기
```

### 태그

`#마크다운` `#학습`처럼 우물 정 기호를 붙입니다. `#프로젝트/진행중`처럼 슬래시로 계층을 만들 수도 있습니다.

### HTML 섞어 쓰기

마크다운으로 안 되는 표현은 HTML을 직접 쓰면 됩니다.

```html
<details>
<summary><b>클릭하여 펼치기</b></summary>
숨겨진 내용
</details>

<kbd>Ctrl</kbd> + <kbd>C</kbd> 로 복사
텍스트에 <mark>형광펜</mark> 칠하기
```

---

## 3장. 심화 활용

옵시디언에서 메타데이터·자동 조회·템플릿까지 다룰 때 쓰는 기법입니다. 당장 필요하지 않다면 건너뛰어도 좋습니다.

### YAML Frontmatter

노트 맨 위에 `---` 사이로 메타데이터를 적습니다.

```yaml
---
title: "프로젝트 기획서"
date: 2026-03-15
tags: [기획, 프로젝트]
status: draft
aliases: ["기획서", "Project Plan"]
cssclasses: [wide-page]
---
```

이 정보는 옵시디언의 Dataview·검색·그래프 뷰에서 활용됩니다.

### Dataview 조회

노트를 데이터베이스처럼 조회해 표나 목록으로 뽑습니다.

```dataview
TABLE status, date
FROM "Projects"
WHERE status = "진행중"
SORT date DESC
```

```dataview
LIST
FROM #학습
WHERE file.mtime >= date(today) - dur(7 days)
SORT file.mtime DESC
```

문장 안에 바로 넣는 인라인 조회도 있습니다 — 현재 노트 생성일 `= this.file.cday`.

### 콜아웃 중첩

콜아웃 안에 제목·목록·다른 콜아웃을 넣을 수 있습니다.

```markdown
> [!abstract] 프로젝트 개요
> ### 목표
> **1분기 마감**까지 다음을 완료합니다.
> 1. API 서버 구축
> 2. 프론트엔드 연동
>
> > [!success] 완료 항목
> > - [x] DB 스키마 설계
>
> > [!failure] 미완료 항목
> > - [ ] 성능 테스트
```

### 표 안에 서식 넣기

표 칸 안에서도 강조·링크·코드가 그대로 동작합니다.

| 기능 | 문법 | 결과 |
|------|------|------|
| 굵게 | `**text**` | **text** |
| 기울임 | `*text*` | *text* |
| 취소선 | `~~text~~` | ~~text~~ |
| 코드 | `` `code` `` | `code` |
| 링크 | `[text](url)` | [옵시디언](https://obsidian.md) |

### 수식 심화

행렬, 조건부 함수, 정적분 같은 표현도 가능합니다.

```markdown
$$
\mathbf{A} = \begin{bmatrix}
a_{11} & a_{12} \\
a_{21} & a_{22}
\end{bmatrix}
$$

$$
f(x) = \begin{cases}
x^2 & \text{if } x \geq 0 \\
-x & \text{if } x < 0
\end{cases}
$$

$$
\int_{0}^{\infty} e^{-x^2} \, dx = \frac{\sqrt{\pi}}{2}
$$
```

### 다이어그램 심화

간트 차트로 일정을 그릴 수 있습니다.

```mermaid
gantt
    title 프로젝트 일정
    dateFormat  YYYY-MM-DD
    section 기획
    요구사항 분석     :done, a1, 2026-01-01, 14d
    설계 문서 작성    :done, a2, after a1, 7d
    section 개발
    백엔드 구현       :active, b1, 2026-01-22, 30d
    프론트엔드 구현   :b2, after b1, 21d
    section 테스트
    통합 테스트       :c1, after b2, 14d
```

문서 결재처럼 상태가 오가는 흐름은 상태 다이어그램으로 그립니다.

```mermaid
stateDiagram-v2
    [*] --> 초안
    초안 --> 검토중: 제출
    검토중 --> 수정필요: 반려
    검토중 --> 승인: 통과
    수정필요 --> 검토중: 재제출
    승인 --> [*]
```

### Templater 자동화

Templater 플러그인을 쓰면 날짜·제목이 저절로 채워집니다.

```
<% tp.date.now("YYYY-MM-DD") %>
<% tp.file.title %>
<% tp.file.cursor() %>
```

조건에 따라 다른 틀을 넣을 수도 있습니다.

```
<% if (tp.file.tags.includes("#회의록")) { %>
## 참석자
## 안건
## 결정사항
<% } else { %>
## 내용
<% } %>
```

### CSS 스니펫으로 꾸미기

`cssclasses` frontmatter와 CSS 파일을 조합하면 노트 모양을 바꿀 수 있습니다.

```yaml
---
cssclasses: [cards, wide-page]
---
```

```css
/* .obsidian/snippets/custom.css */
.wide-page .markdown-preview-view {
    max-width: 100%;
}
```

### 조합 예시 — 프로젝트 대시보드

앞의 기법을 함께 쓰면 이런 문서가 됩니다.

| 영역 | 담당자 | 상태 | 진행률 |
|:----:|:------:|:----:|:------:|
| **백엔드** | *김철수* | ==진행중== | 70% |
| **프론트** | *이영희* | ~~대기~~ → 시작 | 20% |
| **인프라** | *박민수* | `완료` | 100% |

```mermaid
graph LR
    A[Client] --> B[API Gateway]
    B --> C[Auth Service]
    B --> D[Main Service]
    D --> E[(Database)]
    C --> E
```

> [!quote] 참고
> 좋은 문서는 **읽는 사람**을 위해 쓰는 것이지,
> *쓰는 사람*을 위해 쓰는 것이 아닙니다.

---

## 부록 — 빨리 찾아보기

| 하고 싶은 것 | 이렇게 씁니다 |
|---|---|
| 제목 | `# 큰제목` · `## 중제목` · `### 소제목` |
| 굵게 / 기울임 | `**굵게**` / `*기울임*` |
| 취소선 / 형광펜 | `~~취소선~~` / `==형광펜==` |
| 목록 | `- 항목` (순서 없음) · `1. 항목` (순서 있음) |
| 체크리스트 | `- [ ] 할 일` · `- [x] 완료` |
| 링크 | `[보일 글자](주소)` |
| 이미지 | `![설명](주소)` |
| 인용 | `> 인용문` |
| 코드 한 단어 | 백틱 하나로 감싸기 |
| 코드 여러 줄 | 백틱 세 개로 위아래 감싸기 |
| 표 | 칸을 세로줄로 나누고, 다음 줄에 `---`로 구분선 |
| 구분선 | `---` |
| 줄바꿈 | 줄 끝에 공백 두 칸, 또는 빈 줄 하나 |
| 콜아웃 | `> [!note] 제목` |
| 옵시디언 노트 연결 | `[[노트 이름]]` |
| 태그 | `#태그이름` |

---

유소장.ai · 주관 이시도르연구소 주식회사 · 문의 isidor.yu@gmail.com · https://yusozang.ai.kr