마크다운 미리보기

기본 문법

마크다운은 읽기 쉬운 평문으로 서식을 표현하는 방식입니다. 깃허브 README, 노션, 디스코드, 각종 정적 사이트 생성기가 씁니다.

# 제목 1
## 제목 2

**굵게**  *기울임*  ~~취소선~~  `인라인 코드`

- 목록
- 항목
  - 중첩 (공백 2칸 들여쓰기)

1. 번호 목록
2. 두 번째

> 인용문

[링크](https://so-yi.com)
![이미지](경로.png)

---  (수평선)

줄바꿈이 반영되지 않는 이유

표준 마크다운에서는 한 번의 줄바꿈이 무시됩니다. 그냥 공백으로 취급되어 앞 줄에 이어 붙습니다.

문단을 나누려면 빈 줄을 하나 넣어야 합니다.

같은 문단 안에서 줄만 바꾸고 싶다면 방법이 셋입니다.

1. 줄 끝에 공백 두 개를 넣습니다 (전통적이지만 눈에 보이지 않아 실수하기 쉽습니다)
2. 줄 끝에 역슬래시를 붙입니다
3. <br> 태그를 씁니다

깃허브는 코멘트와 이슈에서 줄바꿈을 그대로 반영합니다. 이 도구도 같은 동작(GFM breaks)을 씁니다. 다만 순수 마크다운 파서를 쓰는 환경에서는 다르게 보일 수 있습니다.

GitHub Flavored Markdown

깃허브가 확장한 문법으로, 사실상 표준이 되었습니다.

표

| 항목 | 값 |
|---|---|
| 이름 | 소이툴즈 |

|:---|처럼 콜론을 넣어 정렬을 지정할 수 있습니다. 왼쪽에 콜론이면 왼쪽 정렬, 양쪽이면 가운데, 오른쪽이면 오른쪽입니다.

체크리스트

- [x] 끝난 일
- [ ] 남은 일

코드 블록

백틱 세 개로 감싸고 언어를 지정하면 문법 강조가 적용됩니다.

```js
const sum = (a, b) => a + b;
```

표에서 자주 막히는 것

표는 마크다운 문법 중 가장 손이 많이 가는 부분입니다. 깨졌을 때 확인할 순서입니다.

• 표 위아래에 빈 줄이 있어야 합니다. 바로 앞 문단에 붙여 쓰면 표가 아니라 문장으로 렌더링됩니다.
• 구분선 줄(|---|---|)이 반드시 둘째 줄에 있어야 하고, 열 개수가 머리글과 같아야 합니다.
• 셀 안에 세로 막대(|)를 글자로 쓰려면 \|로 이스케이프합니다. 정규식이나 셸 명령을 표에 넣을 때 자주 걸립니다.
• 셀 안에서 줄을 바꾸는 문법은 없습니다. <br> 태그를 넣는 것이 유일한 방법입니다.
• 셀 병합은 안 됩니다. 병합이 꼭 필요하면 표 전체를 HTML로 쓰거나, 표를 둘로 나누는 편이 낫습니다.

열 너비는 내용에 따라 자동으로 정해지고 마크다운으로는 조절할 수 없습니다. 소스에서 막대를 예쁘게 맞출 필요도 없습니다. |a|b| 처럼 붙여 써도 결과는 같습니다.

코드 블록 안에 백틱을 쓰려면

코드 블록은 백틱 세 개로 열고 닫는데, 그 안에 백틱 세 개짜리 코드 블록을 보여 주고 싶을 때가 있습니다. 마크다운 문법을 설명하는 문서에서 특히 그렇습니다. 이때는 바깥을 백틱 네 개로 감쌉니다. 위 GFM 절의 코드 블록 예시가 바로 그렇게 작성되어 있습니다.

인라인 코드 안에 백틱 하나를 넣으려면 바깥을 백틱 두 개로 감싸고 안쪽 양옆에 공백을 둡니다. code 처럼 씁니다.

주소는 그냥 써도 링크가 됩니다

GFM에서는 https://로 시작하는 주소를 대괄호 없이 적어도 자동으로 링크가 됩니다. 이 도구도 마찬가지입니다. 다만 주소 끝에 마침표나 괄호가 붙어 있으면 그것까지 링크에 포함될 수 있으니, 문장 끝에 주소를 둘 때는 한 칸 띄우거나 <https://...>처럼 꺾쇠로 감싸는 편이 확실합니다.

목록이 깨질 때

가장 흔한 원인은 들여쓰기 칸 수입니다. 중첩 목록은 보통 공백 2칸 또는 4칸으로 들여쓰는데, 파서마다 요구가 조금씩 다릅니다. 한 문서 안에서 일관되게 쓰는 것이 중요합니다.

번호 목록에서 번호가 1부터 다시 시작하는 경우도 있습니다. 마크다운은 실제 숫자를 무시하고 순서대로 다시 매기기 때문입니다. 그래서 1. 1. 1.이라고 써도 1, 2, 3으로 렌더링됩니다.

목록과 코드 블록을 섞을 때는 코드 블록도 목록 수준에 맞춰 들여써야 합니다.

특수문자를 그대로 쓰려면

*, _, #, `, [, ] 같은 문자를 서식이 아니라 글자 그대로 쓰려면 앞에 역슬래시를 붙입니다.

\*별표 그대로\*

_는 특히 주의해야 합니다. snake_case_이름 같은 문자열에서 언더스코어가 기울임으로 해석될 수 있습니다. 이럴 때는 인라인 코드로 감싸는 것이 간편합니다.

HTML은 어디까지 되나요

마크다운은 HTML을 그대로 쓸 수 있게 허용합니다. 표의 셀 병합처럼 마크다운 문법으로 표현할 수 없는 것을 넣을 때 유용합니다.

다만 게시 환경에 따라 제한됩니다. 깃허브는 보안상 script, style, iframe 등을 제거합니다.

이 도구도 렌더링 전에 위험한 태그와 이벤트 속성(onclick 등)을 제거합니다. 남이 보낸 문서를 확인할 때도 안전하게 쓸 수 있습니다.

이미지가 보이지 않는 이유

![설명](./images/chart.png)처럼 상대 경로로 넣은 이미지는 이 도구에서 표시되지 않습니다. 경로가 가리키는 파일이 여기에는 없기 때문입니다. 깃허브에서는 저장소 안의 그 경로를 찾아 보여 주고, 블로그 생성기는 게시 폴더 기준으로 찾습니다. 미리보기에서 이미지까지 확인하려면 https://로 시작하는 절대 주소를 쓰면 됩니다.

이미지 문법에서 대괄호 안의 글은 대체 텍스트입니다. 이미지가 로드되지 않을 때 대신 표시되고, 화면 낭독기가 읽어 주며, 검색엔진이 이미지 내용을 이해하는 근거가 됩니다. 비워 두지 말고 그림이 무엇인지 한 구절 적어 두는 습관이 좋습니다.

HTML 소스로 다른 곳에 옮기기

오른쪽 상단의 보기 방식을 HTML 소스로 바꾸면 변환된 HTML이 그대로 나오고, 복사 버튼으로 가져갈 수 있습니다. 마크다운을 받지 않는 곳에 글을 옮길 때 씁니다.

• 네이버 블로그나 티스토리처럼 HTML 편집 모드가 있는 편집기에 붙여 넣기
• 이메일 뉴스레터 도구의 HTML 블록에 넣기
• 회사 위키가 HTML만 받을 때

반대 방향, 즉 워드나 한글 문서를 마크다운으로 바꾸는 기능은 이 도구에 없습니다. 서식이 복잡한 문서는 자동 변환 결과가 지저분해서 어차피 손질이 필요합니다. 제목·목록·굵게 정도만 쓴 문서라면 본문을 붙여 넣고 문법을 직접 붙이는 편이 빠릅니다.

한글 문서에서 조심할 것

한글 입력기를 쓰다 보면 전각 기호가 들어가는 일이 있습니다. ＃(전각)은 제목이 되지 않고, ＊는 굵게가 되지 않습니다. 결과가 이상하면 기호를 지우고 영문 입력 상태에서 다시 넣어 보세요.

제목 기호 # 뒤에는 공백이 있어야 합니다. #제목은 제목이 아니라 글자 그대로 나옵니다. 깃허브도 같은 규칙입니다.

굵게와 기울임은 한글에서는 * 대신 _를 쓰면 종종 인식되지 않습니다. 한글 낱자는 단어 경계로 취급되지 않아서 _강조_가 그대로 남을 수 있습니다. 한글 문서에서는 **굵게**, *기울임*처럼 별표를 쓰는 편이 안전합니다.

어디에 쓰면 좋은가

README와 기술 문서 — 깃허브에서 그대로 렌더링됩니다.

블로그 원고 — 대부분의 정적 사이트 생성기가 마크다운을 입력으로 받습니다. 이 사이트의 해설 문서도 마크다운으로 작성되어 있습니다.

회의록과 메모 — 평문이라 어디서든 열리고, 나중에 다른 형식으로 변환하기 쉽습니다.

AI 도구와의 대화 — 대부분의 챗봇이 마크다운으로 응답합니다. 문법을 알면 결과를 다른 곳에 옮기기 편합니다.

함께 확인하면 좋은 것

글자수를 세려면 글자수 세기를, 두 원고를 비교하려면 텍스트 비교를 이용하세요.