Markdown 문법을 실제 문서에 적용하기

Markdown은 일반 텍스트에 간단한 기호를 넣어 문서의 구조를 표현한다. README, 개발 문서, 이슈 본문처럼 소스와 결과를 모두 읽어야 하는 곳에 잘 맞는다. 이 글에서는 CommonMark 명세의 기본 문법을 중심으로 설명하고, 표와 작업 목록처럼 GitHub에서 자주 쓰는 확장은 별도로 표시한다. 렌더러마다 지원하는 확장이 다르므로, 게시할 플랫폼의 미리보기에서 결과를 확인해야 한다.

먼저 작은 문서를 만들어 보자. 제목을 하나 쓰고, 다음 문단에 설명을 놓고, 이어서 실행 순서를 목록으로 적는다.

# 배포 절차

새 버전을 배포하기 전에 테스트 결과를 확인한다.

1. 테스트 실행
2. 이미지 빌드
3. 배포 후 상태 확인

이 예제에서 #은 제목, 빈 줄은 문단 경계, 1.부터 시작하는 줄은 순서 있는 목록이다. 기호를 입력했다는 사실보다 문서의 구조가 올바르게 해석되는지가 중요하다. 제목 기호를 문자 그대로 보여 주고 싶으면 \# 배포 절차처럼 역슬래시로 이스케이프하거나 인라인 코드로 감싼다.

제목과 문단

줄 앞에 #을 1개부터 6개까지 놓고 공백을 붙이면 단계별 제목이 된다. # 제목은 최상위 제목, ## 소제목은 그 아래 단계다. #제목처럼 공백을 빼면 의도한 제목으로 해석되지 않을 수 있다. 문서의 제목 계층은 글자 크기를 조절하는 용도가 아니라 독자가 내용을 탐색할 수 있게 하는 구조다. 따라서 # 다음에 바로 ####로 뛰기보다 내용을 기준으로 순서를 정한다.

소스 파일에서 줄을 한 번만 바꾸면 화면에서는 한 문단으로 이어지는 경우가 많다. 새 문단은 빈 줄로 나눈다. 같은 문단에서 꼭 줄만 바꿔야 한다면 줄 끝에 공백 두 칸 또는 역슬래시를 넣는다. 다만 줄 끝 공백은 편집기에서 알아보기 어렵고 자동 정리 과정에서 사라질 수 있다. 특별한 이유가 없다면 문단을 분리하는 편이 읽기 쉽다.

첫 번째 문단은 여기서 끝난다.

두 번째 문단은 빈 줄 다음에 시작한다.

주소: 서울시 종로구\
담당: 운영팀

마지막 두 줄 사이의 역슬래시는 같은 문단 안에서 줄바꿈을 만든다. GitHub의 이슈 입력창과 저장소의 .md 파일은 단일 줄바꿈 처리 방식이 다를 수 있으므로, 파일에 기록할 문서라면 파일 미리보기 기준으로 검사한다.

목록과 인용

순서 없는 목록은 -, +, * 중 하나로 시작하며, 순서 있는 목록은 1.처럼 숫자와 마침표로 시작한다. 한 목록에서는 같은 기호를 일관되게 쓰면 수정하기 편하다. 하위 목록은 부모 항목의 텍스트 시작 위치에 맞춰 들여쓴다. 숫자가 두 자리로 늘면 필요한 들여쓰기 폭도 달라질 수 있다. 아래처럼 예제를 붙여 렌더링 결과를 확인하는 것이 안전하다.

- 빌드
  - 의존성 설치
  - 테스트 실행
- 배포

1. 설정 확인
2. 배포 실행
3. 로그 점검

목록의 항목 안에 문단이나 코드 블록을 넣을 때도 들여쓰기가 중요하다. 들여쓰기가 부족하면 코드가 목록 밖의 별도 문단으로 렌더링될 수 있다. 긴 절차 문서에서는 목록을 무리하게 중첩하기보다 각 단계를 소제목으로 나누는 편이 낫다.

인용은 줄 맨 앞에 >를 붙인다. 여러 줄의 인용문이라면 각 줄에 >를 붙이는 것이 의도를 분명히 한다. >>로 한 단계 더 깊은 인용을 만들 수 있다. 인용 표시가 단순한 강조 상자나 코드 대신 쓰이면 문서의 의미가 흐려질 수 있으니, 실제로 다른 문장이나 문서를 인용할 때 사용한다.

> 장애 기록: 요청이 시간 초과되었다.
> 원인은 아직 확인 중이다.

> 운영팀 설명
>> 데이터베이스 연결부터 확인한다.

강조, 코드, 구분선

*강조* 또는 _강조_는 기울임을, **중요** 또는 __중요__는 굵은 글씨를 만든다. 단어 안의 밑줄이나 기호 주위의 공백은 예상과 다르게 해석될 수 있으므로, 새 문서에서는 읽기 쉬운 * 표기를 일관되게 쓰면 좋다. 명령, 파일명, 변수처럼 글자 그대로 읽어야 하는 것은 역따옴표 한 쌍으로 감싼다. 명령을 굵게 표시하는 것만으로 코드처럼 안전하게 표현되지는 않는다.

여러 줄의 코드는 펜스 코드 블록으로 넣는다. 여는 줄과 닫는 줄에 각각 역따옴표 세 개를 쓰고, 여는 줄 뒤에 언어 이름을 적으면 지원하는 렌더러에서 구문 강조를 적용한다. 언어 이름은 본문 코드가 아니며, 잘못 지정해도 코드 실행 방식이 바뀌지는 않는다.

```bash
git status --short
```

위의 예는 실제로는 다음처럼 보인다.

git status --short

코드 안에 역따옴표 세 개가 포함되어 있다면 바깥 펜스를 더 긴 역따옴표나 물결표(~~~)로 만든다. 들여쓰기 네 칸으로도 코드 블록을 만들 수 있지만, 목록 안에서는 들여쓰기 의미가 섞이므로 펜스가 알아보기 쉽다. ---나 ***를 별도 줄에 쓰면 가로 구분선이 된다. 같은 줄의 문장과 섞거나 목록 항목처럼 들여쓰면 다른 구조가 될 수 있다.

링크, 이미지, 이스케이프

인라인 링크는 [표시할 글](https://example.com) 형태다. 제목 같은 부가 설명이 필요하면 [글](https://example.com "설명")처럼 URL 뒤에 적을 수 있다. 같은 주소를 여러 번 쓴다면 참조 링크가 편하다. 이미지 앞에는 느낌표를 붙인다.

[공식 문서](https://spec.commonmark.org/0.31.2/)
[문법 안내][syntax]
![서버 구성도 설명](이미지-URL)

[syntax]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax

이미지의 대괄호 안에는 이미지를 볼 수 없는 사람도 내용을 이해하도록 대체 텍스트를 적는다. ![이미지]보다는 ![클라이언트가 API 서버를 거쳐 DB에 접근하는 구성도]가 유용하다. 위 코드의 이미지-URL은 실제 이미지 주소로 바꾸어야 한다. 상대 경로를 쓰면 문서를 게시한 위치를 기준으로 해석되므로, 파일을 옮긴 뒤에는 이미지와 링크가 깨지지 않았는지 확인한다.

별표나 해시 기호를 문자 그대로 보여 주려면 \*나 \#처럼 역슬래시를 붙이거나 코드로 감싼다. 원문에 역슬래시를 과하게 넣으면 제목과 목록이 모두 평문으로 출력된다. 이전 문서에서 \#\# 제목이 그대로 보이는 경우가 그 예다. [[문서]] 같은 위키 링크는 모든 Markdown에서 통하는 기본 문법이 아니라 특정 서비스의 확장이므로 대상 플랫폼을 확인한다.

표와 작업 목록은 확장 문법

GitHub Flavored Markdown(GFM)은 CommonMark 위에 표와 작업 목록 같은 기능을 더한다. 이 블로그나 다른 Markdown 렌더러에서도 표를 지원하는지 확인해야 한다. 표의 두 번째 줄은 머리글과 데이터를 구분하며, 각 열에 하이픈이 필요하다.

| 단계 | 확인할 것 |
| --- | --- |
| 빌드 | 테스트 통과 |
| 배포 | 헬스 체크 정상 |

- [ ] 테스트 실행
- [x] 변경 사항 검토

표는 짧은 속성을 비교할 때 적합하다. 셀 안에 긴 코드나 여러 문단이 필요하면 소제목과 목록으로 바꾸는 편이 읽기 쉽다. 체크박스의 클릭 가능 여부 역시 플랫폼마다 다르므로, 정적인 문서에서는 완료 상태를 표현하는 표기로 이해해야 한다.

렌더링이 예상과 다를 때

문법을 기억하는 것보다 소스와 결과를 대조하는 습관이 도움이 된다. 제목이 출력되지 않으면 # 뒤의 공백을, 목록이 끊기면 항목과 하위 항목의 들여쓰기를, 코드가 닫히지 않으면 여닫는 펜스의 길이와 문자를 확인한다. 링크가 깨지면 상대 경로의 기준 위치와 URL의 괄호·공백을 살핀다. 빈 줄 한 개로 문단이 바뀌는지, 단일 줄바꿈이 합쳐지는지도 렌더러에서 직접 확인한다.

정확한 문법과 예외 사례는 CommonMark 명세에 있고, GitHub 환경의 추가 기능은 GitHub 기본 문법 안내에서 확인할 수 있다. 문서가 GitHub 밖에서 렌더링된다면 해당 도구의 Markdown 지원 범위도 함께 보아야 한다.