Markdown 작성 가이드: 구문 빠른 참조와 모범 사례

왜 Markdown으로 작성하는가

Markdown은 가벼운 마크업 언어로, 간단한 기호로 서식을 표현합니다. 작성자는 마우스를 만질 필요 없이 내용에 집중하면 서식이 자동으로 생성됩니다.

장점:

순수 텍스트라 어떤 편집기로든 열 수 있습니다
버전 관리에 유리합니다(Git에서 diff 가능)
HTML, PDF, Word 등 다양한 형식으로 변환할 수 있습니다
학습 비용이 낮아 10분이면 입문할 수 있습니다

기본 구문

제목

# 1급 제목
## 2급 제목
### 3급 제목
#### 4급 제목

한 글에 1급 제목은 하나만 쓰기를 권장합니다.

단락

빈 행으로 단락을 구분합니다. 빈 행이 없으면 같은 단락으로 취급합니다.

강조

**굵게**
*기울임*
~~취소선~~

순서 없는 목록:

- 항목
- 항목
  - 하위 항목(들여쓰기)

순서 있는 목록:

1. 첫 항목
2. 둘째 항목

링크와 이미지

[링크 텍스트](https://example.com)
![이미지 설명](image.png)

코드

인라인: code

코드 블록:

```javascript
const x = 1;


### 인용

인용 내용 둘째 줄


### 구분선


## 확장 구문

### 표

이름	나이
Tom	25


### 작업 목록

완료
미완료


### 각주

본문 내용[^1]

[^1]: 각주 설명


### 취소선

삭제


### 자동 링크

URL이 자동으로 링크로 변환됩니다.

## 작성 팁

### 제목 계층을 명확하게

- 1급 제목: 글 제목
- 2급 제목: 주요 장
- 3급 제목: 작은 절
- 단계를 건너뛰지 마세요(1급에서 바로 3급으로)

### 단락은 간결하게

- 한 단락에 한 관점
- 단락이 너무 길지 않게(3~5줄이 적당)
- 긴 단락은 목록으로 대체

### 목록을 잘 활용

병렬 내용은 목록이 단락보다 명확합니다:
- 단계는 순서 있는 목록
- 병렬 항목은 순서 없는 목록
- 비교 항목은 표

### 코드에 언어 표시

코드 블록에 언어를 표시하면 구문 하이라이트가 적용됩니다:

이미지에 설명 추가

![설명](img.png)의 설명이 중요합니다:

이미지 로드 실패 시 설명이 표시됩니다
화면 읽기 프로그램이 시각 장애 사용자에게 설명을 읽어줍니다
SEO에 유리합니다

링크는 명확하게

링크 텍스트는 목적지 내용을 설명하세요, "여기를 클릭"은 피하세요
외부 링크는 전체 URL 사용
내부 링크는 상대 경로 사용

문서 구성

처음에 목차 배치

긴 문서는 처음에 목차를 두어 각 장으로 연결하세요. 이동이 편리합니다.

장은 제목으로 구분

장은 구분선이 아닌 제목으로 구분하세요. 제목은 계층이 있고 구분선은 없습니다.

코드와 글 분리

코드 블록 앞뒤에 빈 행을 두어 본문과 분리하세요. 읽기가 더 명확해집니다.

이미지는 적절한 위치에

이미지는 관련 글 바로 옆에 두고, 한꺼번에 끝에 두지 마세요. 독자가 순서대로 읽을 때 제때 볼 수 있습니다.

편집기 선택

VS Code

무료, 강력
Markdown 플러그인 설치(예: Markdown All in One)
실시간 미리보기
개발자에게 적합

Typora

WYSIWYG(보이는 대로 편집)
미리보기 창 없이 렌더링된 결과를 직접 편집
유료지만 저렴
집중 작성에 적합

Obsidian

로컬 지식 베이스
양방향 링크
플러그인 풍부
노트와 지식 관리에 적합

온라인 편집기

StackEdit: 온라인 Markdown 편집기
Jianshu: 중국어 작성 플랫폼
임시 작성에 적합

Markdown을 HTML로 변환

Markdown으로 작성한 뒤 웹에 표시하려면 HTML로 변환합니다. Markdown to HTML 도구로 한 번에 변환하세요.

흔한 실수

제목 뒤 공백 없음

#제목은 인식되지 않습니다. # 제목으로 쓰세요(# 뒤 공백).

목록 들여쓰기 오류

하위 목록은 2 또는 4 공백 들여쓰기(파서에 따라 다름). 들여쓰기가 맞지 않으면 하위 목록이 표시되지 않습니다.

코드 블록 미폐쇄


### 특수 문자 미이스케이프

* # 등 기호를 표시하려면 앞에 \\를 붙여 이스케이프: \\*는 *로 표시.

### 표 구문 오류

표에는 헤더 구분 행(| --- |)이 필요. 빠지면 표로 인식하지 않습니다.

### 링크 괄호 불일치

`[링크](url`에서 닫는 괄호가 빠지면 링크가 인식되지 않습니다.

## 모범 사례

### 한 문서에 한 주제

한 글에 한 주제만 다루세요. 여러 주제는 여러 편으로 나누고 링크로 연결하세요.

### 내용 먼저, 서식은 나중에

순수 텍스트 내용을 먼저 쓰고 Markdown 표시를 나중에 추가하세요. 작성하며 서식을 조정하면 흐름이 끊깁니다.

### 스타일 통일

팀 작성 시 스타일을 통일하세요:
- 제목은 몇 급까지
- 목록은 - 또는 *
- 코드 블록 언어 표시
- 목록 최대 중첩 단계

### 원본 파일 보존

Markdown은 원본 파일, HTML/PDF는 생성물입니다. Markdown을 보존하면 수정이 편하고 출력 형식은 매번 다시 생성합니다.

## 요약

Markdown 작성의 핵심: 제목 계층 명확화, 단락 간결화, 목록 활용, 코드 언어 표시, 이미지 설명 추가. 적절한 편집기를 선택하고 스타일을 통일하며 원본 파일을 보존하세요. 표시는 [DocsAll Markdown to HTML 도구](/convert-tools/markdown-to-html)를 사용하며 브라우저에서 실행됩니다.