마크다운 문법 완벽 가이드: 개발자를 위한 필수 문서 작성법

GitHub에서 README 파일을 수정하려는데 문법이 기억나지 않아 검색한 경험, 개발자라면 한 번쯤 있을 겁니다. 마크다운은 배우는 데 10분이면 충분하지만, 가끔 쓰다 보면 세부 문법이 헷갈리곤 하죠. 이 글에서는 자주 쓰는 문법부터 GitHub 전용 확장까지 깔끔하게 정리해봤습니다.

마크다운이란?

마크다운(Markdown)은 2004년 존 그루버(John Gruber)가 만든 경량 마크업 언어입니다. 일반 텍스트로 작성하면서도 구조화된 문서를 만들 수 있도록 설계됐어요. HTML을 직접 작성하는 것보다 훨씬 빠르고, 원본 텍스트 자체도 읽기 쉽다는 게 큰 장점입니다.

처음에는 블로그 글 작성용으로 시작했지만, 지금은 GitHub, GitLab, Notion, Slack, Reddit 등 수많은 플랫폼에서 표준 문서 포맷으로 사용됩니다. 개발자에게는 사실상 필수 기술이 됐어요.

왜 마크다운을 써야 할까?

어디서든 작동합니다: 마크다운 파일(.md)은 메모장에서도 열 수 있습니다. 특정 프로그램에 종속되지 않아서 10년 뒤에도 문제없이 읽을 수 있어요. 워드 파일은 버전 호환 문제가 생기지만, 마크다운은 그런 걱정이 없습니다.

버전 관리와 찰떡: Git으로 변경 이력을 추적할 때, 바이너리 파일인 워드 문서는 diff를 볼 수 없습니다. 하지만 마크다운은 텍스트 기반이라 어떤 줄이 바뀌었는지 한눈에 파악할 수 있어요.

작성 속도가 빠릅니다: 마우스로 메뉴를 클릭해서 서식을 지정하는 대신, 키보드에서 손을 떼지 않고 글을 쓸 수 있습니다. 개발자에게 이건 큰 차이예요.

기본 문법 정리

제목(Heading): # 기호로 제목을 만듭니다. #이 1개면 가장 큰 제목(h1), 6개면 가장 작은 제목(h6)이에요. 보통 문서에서는 h1은 하나만 쓰고, 본문 구조는 h2부터 시작하는 게 관례입니다.

굵게/기울임: 텍스트를 **로 감싸면 굵게, *로 감싸면 기울임이 됩니다. ***세 개를 쓰면 굵은 기울임***도 가능해요. 밑줄은 마크다운 표준에는 없습니다.

취소선: ~~물결 두 개~~로 감싸면 취소선이 그어집니다. 수정 사항을 표시할 때 유용해요.

줄바꿈: 마크다운에서 단순히 엔터를 한 번 치면 같은 단락으로 이어집니다. 강제 줄바꿈을 하려면 줄 끝에 공백 두 칸을 넣거나, 빈 줄을 하나 넣어 새 단락을 시작하세요.

목록 만들기

순서 없는 목록: -, *, + 중 아무거나 사용할 수 있습니다. 일관성을 위해 하나만 골라 쓰는 게 좋아요. 들여쓰기(공백 2~4칸)를 하면 하위 목록이 됩니다.

순서 있는 목록: 1., 2., 3. 처럼 숫자와 점을 붙입니다. 재밌는 점은, 실제 숫자가 뭐든 마크다운이 자동으로 순서를 매긴다는 겁니다. 전부 1.로 써도 렌더링하면 1, 2, 3으로 나와요. 하지만 가독성을 위해 올바른 숫자를 쓰는 걸 권장합니다.

링크와 이미지

링크: [표시 텍스트](URL) 형식입니다. [Google](https://google.com)처럼 쓰면 됩니다. 같은 링크를 여러 번 쓸 때는 참조 방식을 사용하면 깔끔해요.

이미지: 링크 앞에 !를 붙이면 됩니다.  형식이에요. 대체 텍스트는 이미지가 로드되지 않을 때 표시되니, 의미 있는 설명을 적어주는 게 접근성에 좋습니다.

코드 작성하기

인라인 코드: 백틱(`)으로 감싸면 됩니다. 문장 중간에 `console.log()`처럼 코드를 넣을 때 사용해요.

코드 블록: 백틱 세 개(```)로 시작하고, 언어 이름을 적으면 문법 하이라이팅이 적용됩니다. JavaScript면 ```javascript, Python이면 ```python으로 시작하세요. 닫을 때도 ```를 사용합니다.

표(테이블) 만들기

파이프(|)와 하이픈(-)으로 표를 만들 수 있습니다. 헤더 행 아래에 구분선을 넣고, 정렬은 콜론(:)으로 지정합니다. 왼쪽 정렬은 :---, 가운데 정렬은 :---:, 오른쪽 정렬은 ---: 입니다. 칸 너비가 안 맞아도 렌더링할 때는 자동으로 정렬되니 걱정하지 마세요.

인용문과 수평선

인용문: > 기호로 시작합니다. 여러 줄에 걸쳐 쓸 수 있고, >>로 중첩 인용도 가능합니다. 다른 사람의 글을 인용하거나 주의사항을 강조할 때 유용해요.

수평선: ---, ***, ___ 중 하나를 빈 줄 사이에 넣으면 수평선이 그어집니다. 섹션을 시각적으로 구분할 때 사용합니다.

GitHub Flavored Markdown(GFM) 확장

GitHub에서 사용하는 마크다운은 표준에 몇 가지 기능을 추가했습니다.

체크박스: - [ ]는 빈 체크박스, - [x]는 체크된 체크박스입니다. TODO 리스트나 이슈 트래킹에 아주 편리해요. PR 리뷰 체크리스트를 만들 때 많이 씁니다.

자동 링크: URL을 그냥 적으면 자동으로 클릭 가능한 링크로 변환됩니다. [텍스트](URL) 형식을 쓰지 않아도 돼요.

이슈/PR 참조: #123처럼 쓰면 자동으로 해당 이슈나 PR로 링크됩니다. 다른 저장소는 user/repo#123 형식으로 참조할 수 있어요.

마크다운 활용 팁

README 작성: 프로젝트의 첫인상을 결정합니다. 프로젝트 설명, 설치 방법, 사용법, 라이선스를 포함하세요. 뱃지를 달면 프로젝트 상태를 한눈에 보여줄 수 있어요.

문서 구조화: h2를 최상위 섹션으로, h3를 하위 섹션으로 사용하는 2단계 구조가 가장 읽기 좋습니다. 목차는 [섹션명](#섹션명)으로 내부 링크를 만들어 추가할 수 있어요.

미리보기 활용: VS Code, Typora 같은 에디터에서 실시간 미리보기를 켜고 작성하면 실수를 바로 잡을 수 있습니다. 웹에서도 온라인 마크다운 미리보기 도구를 활용하면 브라우저만으로 바로 확인할 수 있어요.