마크다운 문법 정리: 제목·목록·표·코드 블록 쓰는 법과 자주 깨지는 경우

제목, 강조, 목록, 링크, 표, 코드 블록 등 마크다운 기본 문법을 입력과 결과 대응표로 정리하고, 줄바꿈·목록 들여쓰기·표 정렬처럼 렌더링이 깨지는 원인을 설명합니다.

마크다운을 쓰다 보면 "분명 목록으로 썼는데 한 줄로 합쳐진다", "표가 그대로 글자로 나온다" 같은 문제를 겪습니다. 대부분 문법 자체보다 빈 줄, 들여쓰기, 렌더러 종류 때문입니다. 자주 쓰는 문법을 입력과 결과로 비교하고, 깨지는 원인을 정리했습니다.

1. 기본 문법 한눈에 보기

2. 코드 블록

여러 줄 코드는 백틱 3개(```)로 위아래를 감쌉니다. 첫 줄 뒤에 언어 이름(예: json, js)을 붙이면 문법 색상이 적용되는 도구가 많습니다. 코드 안에 백틱 3개가 들어 있다면 바깥을 백틱 4개로 감싸야 합니다. 들여쓰기 4칸으로도 코드 블록이 되기 때문에, 일반 문단을 우연히 4칸 들여 쓰면 코드로 바뀌는 일이 생깁니다.

3. 표 만들기

표는 헤더 줄, 구분 줄, 데이터 줄로 구성합니다. 구분 줄의 콜론으로 정렬을 지정합니다.

표는 원래 마크다운 표준에 없고 GitHub 방식(GFM) 같은 확장입니다. 셀 안에서 줄바꿈이 필요하면 도구에 따라 <br>을 써야 하고, 셀 안에 | 문자를 넣으려면 \| 로 이스케이프합니다.

4. 목록이 깨지는 대표 원인

• 목록 앞에 빈 줄이 없음: 문단 바로 아래에 - 항목을 붙여 쓰면 목록이 아니라 문장 일부로 합쳐지는 렌더러가 있습니다. 목록 위에는 빈 줄을 두세요.
• 하위 목록 들여쓰기: 번호 목록 아래의 하위 항목은 보통 3~4칸, 글머리 목록은 2칸 이상 들여써야 합니다. 탭과 공백을 섞으면 깨집니다.
• 번호 뒤 점 누락: 1) 형식은 일부 도구에서만 목록으로 인식됩니다.
• 체크박스: - [ ] 와 - [x] 는 GFM 확장이며 일반 마크다운 뷰어에서는 글자 그대로 보입니다.

5. 줄바꿈과 문단

마크다운은 줄바꿈 한 번을 같은 문단의 공백으로 취급합니다. 문단을 나누려면 빈 줄을 하나 넣고, 같은 문단 안에서 줄만 바꾸려면 줄 끝에 공백 2칸 또는 역슬래시를 붙입니다. 에디터가 줄 끝 공백을 자동 삭제하면 줄바꿈이 사라지므로 주의하세요.

6. 특수문자 이스케이프

*, _, #, [, ], `, | 같은 기호를 문법이 아닌 글자 그대로 쓰려면 앞에 역슬래시를 붙입니다. 예를 들어 \*별표\* 는 별표가 그대로 보입니다. 가격 표기에서 숫자 앞 # 를 쓰거나 파일 이름에 _가 여러 번 들어가면 의도치 않은 서식이 생기므로 코드 서식으로 감싸는 방법도 있습니다.

7. 어디에 쓰고 어디서 확인하나

GitHub README, 개발 문서 사이트, 노션, 옵시디언 등은 모두 마크다운을 지원하지만 세부 확장이 다릅니다. 작성한 글을 여러 곳에 올릴 계획이라면 가장 보수적인 문법(제목, 굵게, 목록, 링크, 코드)만 쓰는 편이 안전하고, 표와 체크박스는 대상 도구에서 한 번 미리 보기로 확인한 뒤 사용하세요.

자주 묻는 질문

참고한 공식 자료

• CommonMark 명세
• GitHub Flavored Markdown 명세

이 글은 일반적인 기준을 설명하는 정보이며 개인별 법률·세무 판단을 대신하지 않습니다. 중요한 결정 전에는 본문에 적은 공식 기관 자료나 전문가 상담으로 확인하세요. 내용 오류는 문의 페이지로 알려주시면 확인 후 수정합니다.